home *** CD-ROM | disk | FTP | other *** search
/ Tech Arsenal 1 / Tech Arsenal (Arsenal Computer).ISO / tek-01 / dmalloc.zip / INSTALL.LIB / DOC / DMALLOC.DOC < prev    next >
Text File  |  1992-11-01  |  135KB  |  3,530 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.           ********************************************************
  16.  
  17.           DDDDD   MM    MM                                    (TM)
  18.            DD DD  MMM  MMM                                        
  19.            DD  DD MMMMMMMM                                        
  20.            DD  DD MMMMMMMM   AA    LLLL    LLLL      OOO     CCCC 
  21.            DD  DD MM MM MM  AAAA    LL      LL      OO OO   CC  CC
  22.            DD  DD MM    MM AA  AA   LL      LL     OO   OO CC     
  23.            DD  DD MM    MM AA  AA   LL      LL     OO   OO CC     
  24.            DD  DD MM    MM AAAAAA   LL   L  LL   L OO   OO CC     
  25.            DD DD  MM    MM AA  AA   LL  LL  LL  LL  OO OO   CC  CC
  26.           DDDDD   MM    MM AA  AA  LLLLLLL LLLLLLL   OOO     CCCC 
  27.  
  28.           ********************************************************
  29.  
  30.                                    v 1.0
  31.  
  32.  
  33.  
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.                        The C Language Malloc Debugger
  41.  
  42.                                      by
  43.  
  44.                            Ernest E. Vogelsinger
  45.  
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.                                                 ┌─────────┐
  58.                                           ┌─────┴───┐     │              (R)
  59.                                         ──│         │o    │──────────────────
  60.                                           │   ┌─────┴╨──┐ │  Association of
  61.                                           │   │         │─┘  Shareware
  62.                                           └───│    o    │    Professionals
  63.                                         ──────│    ║    │────────────────────
  64.                                               └────╨────┘    MEMBER
  65.  
  66.  
  67.      ***************** IMPORTANT WARRANTY INFORMATION ****************
  68.  
  69.  
  70.                            DMalloc, Version 1.00
  71.  
  72.                *** PLEASE READ THIS INFORMATION CAREFULLY ***
  73.  
  74.  
  75.      TRIAL USE (SHAREWARE EVALUATION VERSION) WARRANTY:
  76.      --------------------------------------------------
  77.  
  78.      The Shareware evaluation (trial use) version is provided AS IS.
  79.      Ernest Vogelsinger MAKES NO WARRANTY OF ANY KIND, EXPRESSED OR
  80.      IMPLIED, INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF
  81.      MERCHANTABILITY AND/OR FITNESS FOR A PARTICULAR PURPOSE.
  82.  
  83.  
  84.      REGISTERED VERSION ONLY WARRANTY:
  85.      ---------------------------------
  86.  
  87.      Ernest Vogelsinger warrants the physical diskette(s) and physical
  88.      documentation provided with registered versions to be free of
  89.      defects in materials and workmanship for a period of ninety days
  90.      from the date of registration.  If Ernest Vogelsinger receives
  91.      notification within the warranty period of defects in materials
  92.      or workmanship, and such notification is determined by Ernest
  93.      Vogelsinger to be correct, Ernest Vogelsinger will replace the
  94.      defective diskette(s) or documentation.
  95.  
  96.      The entire and exclusive liability and remedy for breach of this
  97.      Limited Warranty shall be limited to replacement of defective
  98.      diskette(s) or documentation and shall not include or extend to
  99.      any claim for or right to recover any other damages, including
  100.      but not limited to, loss of profit, data, or use of the software,
  101.      or special, incidental, or consequential damages or other similar
  102.      claims, even if Ernest Vogelsinger has been specifically advised
  103.      of the possibility of such damages.  In no event will Ernest
  104.      Vogelsinger's liability for any damages to you or any other person
  105.      ever exceed the lower of suggested list price or actual price
  106.      paid for the license to use the software, regardless of any form
  107.      of the claim.
  108.  
  109.      Ernest Vogelsinger SPECIFICALLY DISCLAIMS ALL OTHER WARRANTIES,
  110.      EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, ANY IMPLIED
  111.      WARRANTY OF MERCHANTABILITY AND/OR FITNESS FOR A PARTICULAR
  112.      PURPOSE.
  113.  
  114.      ***************** IMPORTANT WARRANTY INFORMATION ****************
  115.  
  116.  
  117.                DMalloc is a trademark of Ernest Vogelsinger.
  118.           Soft-ICE and Bounds-Checker are registered trademarks of
  119.                          Nu-Mega Technologies, Inc.
  120.         Microsoft, MS-DOS, and CodeView are registered trademarks of
  121.                               Microsoft Corp.
  122.  
  123.          Any other product names used herein are for identification
  124.       purposes only and may be trademarks or registered trademarks of
  125.                         their respective companies.
  126.  
  127.                1991-1992 Ernest Vogelsinger, Vienna, Austria
  128.  
  129.  
  130. 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   1
  131.      1.1. What is DMalloc?. . . . . . . . . . . . . . . . . . . . . . . .   1
  132.      1.2. Requirements. . . . . . . . . . . . . . . . . . . . . . . . . .   1
  133.      1.3. Why DMalloc Instead of a BRAND X Heap Checker . . . . . . . . .   1
  134.      1.4. Summary of Features . . . . . . . . . . . . . . . . . . . . . .   2
  135.      1.5. What is Shareware . . . . . . . . . . . . . . . . . . . . . . .   2
  136.      1.6. DMalloc Unregistered Evaluation Version . . . . . . . . . . . .   3
  137.      1.7. Registration. . . . . . . . . . . . . . . . . . . . . . . . . .   3
  138.           1.7.1. Registering Your Evaluation Copy . . . . . . . . . . . .   5
  139.      1.8. Distribution Policies . . . . . . . . . . . . . . . . . . . . .   5
  140.      1.9. Association of Shareware Professionals Ombudsman. . . . . . . .   6
  141.  
  142. 2. Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   7
  143.      2.1. From a Compressed Archive . . . . . . . . . . . . . . . . . . .   7
  144.      2.2. From a Distribution Disk. . . . . . . . . . . . . . . . . . . .   7
  145.      2.3. Checking the Completed Installation . . . . . . . . . . . . . .   7
  146.      2.4. Documentation . . . . . . . . . . . . . . . . . . . . . . . . .   8
  147.           2.4.1. Registration Form. . . . . . . . . . . . . . . . . . . .   8
  148.           2.4.2. The Manual . . . . . . . . . . . . . . . . . . . . . . .   9
  149.      2.5. A Quick Start . . . . . . . . . . . . . . . . . . . . . . . . .   9
  150.      2.6. Where to from here? . . . . . . . . . . . . . . . . . . . . . .  10
  151.      2.7. Support & Thanks. . . . . . . . . . . . . . . . . . . . . . . .  10
  152.  
  153. 3. The Demonstration Program. . . . . . . . . . . . . . . . . . . . . . .  12
  154.      3.1. Compiling the Demo Program. . . . . . . . . . . . . . . . . . .  12
  155.      3.2. Running the Demo. . . . . . . . . . . . . . . . . . . . . . . .  12
  156.      3.3. DMalloc Startup . . . . . . . . . . . . . . . . . . . . . . . .  13
  157.      3.4. Heap Overview . . . . . . . . . . . . . . . . . . . . . . . . .  13
  158.      3.5. Total Heap Status . . . . . . . . . . . . . . . . . . . . . . .  14
  159.      3.6. Detecting Heap Problems . . . . . . . . . . . . . . . . . . . .  14
  160.      3.7. Invalid Pointer Warning . . . . . . . . . . . . . . . . . . . .  15
  161.      3.8. Determining Action, Setting Breakpoints . . . . . . . . . . . .  15
  162.      3.9. Null Pointer Assignments. . . . . . . . . . . . . . . . . . . .  16
  163.      3.10. Fatal Heap Errors. . . . . . . . . . . . . . . . . . . . . . .  16
  164.  
  165. 4. Dynamic Memory and DMalloc . . . . . . . . . . . . . . . . . . . . . .  17
  166.      4.1. Dynamic Memory Layout . . . . . . . . . . . . . . . . . . . . .  17
  167.      4.2. DMalloc and Dynamic Memory. . . . . . . . . . . . . . . . . . .  17
  168.      4.3. Tracking the Functions. . . . . . . . . . . . . . . . . . . . .  18
  169.      4.4. Checking the Heap . . . . . . . . . . . . . . . . . . . . . . .  18
  170.      4.5. Types of Heap Corruption. . . . . . . . . . . . . . . . . . . .  19
  171.           4.5.1. Lead Corruption. . . . . . . . . . . . . . . . . . . . .  19
  172.           4.5.2. Trail Corruption . . . . . . . . . . . . . . . . . . . .  19
  173.           4.5.3. Odd/Even Problem . . . . . . . . . . . . . . . . . . . .  19
  174.           4.5.4. Mavericks. . . . . . . . . . . . . . . . . . . . . . . .  19
  175.      4.6. Null Pointer Assignments. . . . . . . . . . . . . . . . . . . .  20
  176.      4.7. Far Null Pointer Assignments. . . . . . . . . . . . . . . . . .  20
  177.      4.8. Watchpoints . . . . . . . . . . . . . . . . . . . . . . . . . .  20
  178.      4.9. Savepoints. . . . . . . . . . . . . . . . . . . . . . . . . . .  20
  179.  
  180. 5. DMalloc In Detail. . . . . . . . . . . . . . . . . . . . . . . . . . .  21
  181.      5.1. About DMalloc Windows . . . . . . . . . . . . . . . . . . . . .  21
  182.      5.2. Function Keys . . . . . . . . . . . . . . . . . . . . . . . . .  21
  183.      5.3. Information Window. . . . . . . . . . . . . . . . . . . . . . .  22
  184.           5.3.1. "You can" - Select the Next Action . . . . . . . . . . .  22
  185.           5.3.2. "Breakpoint:". . . . . . . . . . . . . . . . . . . . . .  23
  186.      5.4. Setup Window. . . . . . . . . . . . . . . . . . . . . . . . . .  23
  187.           5.4.1. Alert on problem . . . . . . . . . . . . . . . . . . . .  23
  188.  
  189.  
  190. ----- DMalloc -------------------------------------- Table of Contents ------
  191.  
  192.  
  193.           5.4.2. Popup on saved . . . . . . . . . . . . . . . . . . . . .  24
  194.           5.4.3. Cycles for popup . . . . . . . . . . . . . . . . . . . .  24
  195.           5.4.4. Heap check cycles. . . . . . . . . . . . . . . . . . . .  24
  196.           5.4.5. Popup for file/line. . . . . . . . . . . . . . . . . . .  24
  197.           5.4.6. Startup screen . . . . . . . . . . . . . . . . . . . . .  24
  198.           5.4.7. Shutdown screen. . . . . . . . . . . . . . . . . . . . .  25
  199.           5.4.8. Alternate monitor. . . . . . . . . . . . . . . . . . . .  25
  200.           5.4.9. Number of handles. . . . . . . . . . . . . . . . . . . .  25
  201.      5.5. Colors Window . . . . . . . . . . . . . . . . . . . . . . . . .  26
  202.      5.6. Heap Entries Window . . . . . . . . . . . . . . . . . . . . . .  27
  203.           5.6.1. Detecting Corrupted Entries. . . . . . . . . . . . . . .  29
  204.           5.6.2. "Repairing" Corrupted Entries. . . . . . . . . . . . . .  29
  205.           5.6.3. Watchpoints ("Tags") . . . . . . . . . . . . . . . . . .  29
  206.           5.6.4. Savepoints . . . . . . . . . . . . . . . . . . . . . . .  30
  207.      5.7. Selection Window. . . . . . . . . . . . . . . . . . . . . . . .  30
  208.      5.8. Dump Window . . . . . . . . . . . . . . . . . . . . . . . . . .  31
  209.           5.8.1. Editing Data . . . . . . . . . . . . . . . . . . . . . .  31
  210.      5.9. Heap Status Window. . . . . . . . . . . . . . . . . . . . . . .  32
  211.      5.10. The Configuration File . . . . . . . . . . . . . . . . . . . .  32
  212.           5.10.1. Configuring the Library . . . . . . . . . . . . . . . .  33
  213.  
  214. 6. How to use DMalloc . . . . . . . . . . . . . . . . . . . . . . . . . .  33
  215.      6.1. Linking DMalloc to the Program. . . . . . . . . . . . . . . . .  33
  216.           6.1.1. Using Different Compilers. . . . . . . . . . . . . . . .  33
  217.           6.1.2. Using Overlay Linkers. . . . . . . . . . . . . . . . . .  33
  218.      6.2. Recompiling . . . . . . . . . . . . . . . . . . . . . . . . . .  34
  219.           6.2.1. Effects and Side-Effects when using the
  220.                _DMALLOC switch. . . . . . . . . . . . . . . . . . . . . .  34
  221.      6.3. Calling the DMalloc API . . . . . . . . . . . . . . . . . . . .  35
  222.      6.4. DMalloc and Spawn . . . . . . . . . . . . . . . . . . . . . . .  35
  223.      6.5. DMalloc and Video . . . . . . . . . . . . . . . . . . . . . . .  35
  224.           6.5.1. The Relocatable Screen Interface (RLSI). . . . . . . . .  36
  225.           6.5.2. Calling RLSI . . . . . . . . . . . . . . . . . . . . . .  36
  226.      6.6. DMalloc and Debuggers . . . . . . . . . . . . . . . . . . . . .  36
  227.           6.6.1. Soft-ICE(tm) . . . . . . . . . . . . . . . . . . . . . .  37
  228.           6.6.2. CodeView(r). . . . . . . . . . . . . . . . . . . . . . .  37
  229.           6.6.3. Other Debuggers. . . . . . . . . . . . . . . . . . . . .  37
  230.      6.7. DMalloc and Bounds-Checker(r) . . . . . . . . . . . . . . . . .  37
  231.      6.8. DMalloc and atexit() processing . . . . . . . . . . . . . . . .  38
  232.  
  233. 7. The Programming API. . . . . . . . . . . . . . . . . . . . . . . . . .  38
  234.      7.1. Activating the API. . . . . . . . . . . . . . . . . . . . . . .  38
  235.      7.2. Removing the API Calls. . . . . . . . . . . . . . . . . . . . .  38
  236.  
  237. 8. API Reference. . . . . . . . . . . . . . . . . . . . . . . . . . . . .  39
  238.  
  239. 9. Problem Solving, and Frequently Asked Questions. . . . . . . . . . . .  43
  240.  
  241. Appendix A - The Library Serialization Program DMSerial . . . . . . . . .  46
  242. Appendix B - The Library Configuration Program DMConfig . . . . . . . . .  47
  243. Appendix C - The Legal Department (License Agreement) . . . . . . . . . .  48
  244. Appendix D - How to Send Email to Compuserve. . . . . . . . . . . . . . .  49
  245.      D.1 How to obtain a CompuServe Account . . . . . . . . . . . . . . .  49
  246.      D.2 MCI. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  49
  247.      D.3 Internet . . . . . . . . . . . . . . . . . . . . . . . . . . . .  50
  248.      D.4 Telex, Twx . . . . . . . . . . . . . . . . . . . . . . . . . . .  50
  249.      D.5 X.400. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  51
  250.      D.6 MHS. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  52
  251.  
  252.  
  253. ----- DMalloc -------------------------------------- Table of Contents ------
  254.  
  255.  
  256. 1. Introduction
  257.  
  258. 1.1. What is DMalloc?
  259.      DMalloc is a full-featured, convenient, windowed pop-up
  260.      dynamic memory debugger for C language applications. It
  261.      monitors heap integrity and the dynamic memory requirements
  262.      of an application. From a technical point of view DMalloc
  263.      is a library that is linked with the program's object fi-
  264.      les.
  265.  
  266. 1.2. Requirements
  267.      DMalloc is currently available for Microsoft(r) C compilers
  268.      (v.5.1, 6+, and 7). Different compiler versions may be sup-
  269.      ported with future upgrades.
  270.      DMalloc can only be used with the "large" memory model (far
  271.      code, far data).(1)
  272.      DOS version should be 3.30 or above.(2)
  273.      DMalloc will add about 41kB to code and data size, and -
  274.      depending on the setup - 2 to 141 kB of dynamic (far) memo-
  275.      ry.
  276.  
  277. 1.3. Why DMalloc Instead of a BRAND X Heap Checker
  278.      DMalloc checks the integrity of dynamic memory. Unlike ot-
  279.      her packages, it monitors the allocated memory units them-
  280.      selves, instead of tracking out-of-bounds segment accesses.
  281.      Thus it is an ideal companion to 386-based bound checking
  282.      utilities such as Bounds-Checker(tm). For more information
  283.      on segments and allocation units refer to section 4, page 17.
  284.  
  285.      You don't need to recompile a single source module. DMalloc
  286.      tracks all calls to memory allocation/deallocation, even in
  287.      third-party code and libraries.
  288.  
  289.      Null pointer assignments are detected much earlier than by
  290.      the runtime library (which detects them at the end of the
  291.      program). And, as a special feature for the large memory
  292.      model, even assignments to far null pointers (the interrupt
  293.      table) are detected and repaired (if possible) to keep the
  294.      interrupt table intact.
  295.  
  296.      DMalloc can cooperate with other debuggers. Special support
  297.      has been built in for CodeView(r) and Soft-ICE(tm) debug-
  298.      gers.
  299.  
  300.      DMalloc can be used as a background watchdog as well as to
  301.      interactively review the requirements and fragmentation
  302.      status of the dynamic heap.
  303.  
  304.      DMalloc supports an alternate monitor to allow debugging of
  305.      graphical applications.
  306.  
  307.  
  308.  
  309.      ____________________
  310.  
  311.      1   Future versions may support different memory models.
  312.      2   DMalloc was tested with DOS versions 3.30,  4.01, and 5.00.
  313.          However, nothing special is needed from DOS, so other 
  314.          versions should do as well.
  315.  
  316. ----- DMalloc ------------------------------------------- Page 1 of 52 ------
  317.  
  318.  
  319.      DMalloc can remember corrupted allocation units from one
  320.      session to the next, allowing you to monitor suspect units
  321.      from the moment of their allocation.
  322.  
  323.      DMalloc provides a rich API to allow fine-tuning of debug-
  324.      ging setups from within the source code.
  325.  
  326.      DMalloc is shareware, allowing you to fully evaluate it for
  327.      30 days. If you don't like it, you don't pay for it. Howe-
  328.      ver, DMalloc is a very professional debug utility, and not
  329.      playware.
  330.  
  331. 1.4. Summary of Features
  332.      ■    Tracking of allocation and deallocation of dynamic me-
  333.           mory
  334.      ■    Integrity check on every allocated unit
  335.      ■    Integrity check on the data segment null region (null
  336.           pointer assignment error)
  337.      ■    Integrity check and repair on the far-null region (the
  338.           interrupt table)
  339.      ■    Automatic pop-up when a heap problem is encountered
  340.      ■    Interactive pop-up by pressing [PrtSc]
  341.      ■    Automatic pop-up when allocating memory that has been
  342.           corrupted in the last debug session, or that has been
  343.           selected to be saved
  344.      ■    Pop-up when freeing/reallocating/expanding selected
  345.           units (Watchpoint feature)
  346.      ■    Graceful program termination when the heap is destroyed
  347.           and the program would be likely to hang
  348.      ■    Sorted display of data segments and all allocated units
  349.      ■    Assignment of allocation units to source file and line
  350.           (when recompiling)
  351.      ■    Optional selective display selection by specifying
  352.           source file and line number
  353.      ■    Viewing and editing of allocation unit contents
  354.      ■    Possibility to set debugger breakpoints
  355.      ■    Extensive setup options to tailor DMalloc's behaviour
  356.           to the current debug context, and changing setup op-
  357.           tions at runtime
  358.      ■    Alternate monitor support to allow debugging of graphi-
  359.           cal applications
  360.      ■    User-defined screen colors on both monitors
  361.      ■    Automatic save of setup options, and corrupted and se-
  362.           lected allocation units on an per-application basis
  363.      ■    Rich API for program/debugger interaction
  364.  
  365. 1.5. What is Shareware
  366.      Shareware distribution gives users a chance to try software
  367.      before buying it.  If you try a Shareware program and con-
  368.      tinue to use it, you are expected to register.
  369.  
  370.      Copyright laws apply to both Shareware and commercial soft-
  371.      ware, and the copyright holder retains all rights. Sharewa-
  372.      re authors are accomplished programmers, just like commer-
  373.      cial authors, and the programs are of comparable quality -
  374.      in both cases, there are good programs and bad ones! The
  375.      main difference between the two is in the method of
  376.      distribution.
  377.  
  378.  
  379. ----- DMalloc ------------------------------------------- Page 2 of 52 ------
  380.  
  381.  
  382.      So Shareware is a distribution method, not a type of soft-
  383.      ware. You should find software that suits your needs and
  384.      pocketbook, whether it's commercial or Shareware.  The Sha-
  385.      reware system makes fitting your needs easier, because you
  386.      can try before you buy.  And because the overhead is low,
  387.      prices are low also.
  388.  
  389.      Shareware has the ultimate money-back guarantee - if you
  390.      don't use the product, you don't pay for it.
  391.  
  392. 1.6. DMalloc Unregistered Evaluation Version
  393.      The unregistered version of DMalloc is fully functional.
  394.      When a program linked with the unregistered version is
  395.      starting and terminating, a window will pop up to remind
  396.      you that you are using an unregistered copy. To make this
  397.      reminder screen go away, hit any key.
  398.  
  399. 1.7. Registration
  400.      DMalloc is copyrighted Shareware, it is NOT PUBLIC DOMAIN,
  401.      it is NOT FREE.  If you find DMalloc of value and continue
  402.      to use it after a thirty day evaluation period PLEASE regi-
  403.      ster your copy of DMalloc.
  404.  
  405.      When you register you receive:
  406.      ■    a serial number and license for one copy of DMalloc
  407.      ■    a diskette with a registered copy of DMalloc
  408.      ■    six months free support
  409.      ■    any technical updates of DMalloc v 1.0 available at
  410.           that time
  411.      ■    a printed and bound manual
  412.      ■    a configuration utility to modify the DMalloc library
  413.           to your setup requirements (see appendix B, page 41)
  414.      ■    free interim updates when available
  415.      ■    version 2.0 at a greatly reduced fee
  416.      ■    reduced registration fee (by 10.00 US$) of the
  417.           Z/Install Installation program
  418.      ■    a greater voice in suggesting future enhancements
  419.      ■    the satisfaction of supporting the shareware concept
  420.  
  421.      If you have not previously registered, and after an evalua-
  422.      tion of DMalloc you wish to register, or if you would just
  423.      like a registered copy to be shipped out to you, the cost
  424.      is:
  425.  
  426.              41.00 US$
  427.          s/h  6.00 US$
  428.          -------------
  429.              47.00 US$
  430.  
  431.      To have an additional manual shipped, the cost is
  432.  
  433.              11.00 US$
  434.          s/h  6.00 US$
  435.          -------------
  436.              17.00 US$
  437.  
  438.  
  439.  
  440.  
  441.  
  442. ----- DMalloc ------------------------------------------- Page 3 of 52 ------
  443.  
  444.  
  445.      To register, or to order additional printed manuals, fill
  446.      out the registration form (REGISTER.FRM, see section 2.4.1,
  447.      page 8), add a check, made payable to Ernest Vogelsinger,
  448.      or money order (if not registering with credit card), and
  449.      send them in using one of three options:
  450.  
  451.      1)   By regular mail to:
  452.                Ernest Vogelsinger
  453.                Hietzinger Hauptstrasse 40 c
  454.                A-1130 Vienna, Austria
  455.  
  456.           North America only:
  457.                Ben Morris
  458.                SpeedSoft Development
  459.                2232 Tashy Place
  460.                V8N4R6 Victoria BC, Canada
  461.  
  462.      2)   By telephone or fax: if this is by VISA or MASTERCARD
  463.           credit card, call
  464.  
  465.                Tel:  (+43) 1 876 46 090      (international line)
  466.                      ORDERS ONLY!
  467.                      SUPPORT IS NOT AVAILABLE AT THAT NUMBER.
  468.                Fax:  (+43) 1 876 46 094      (international line)
  469.  
  470.           North America only:
  471.                
  472.           if you want to register by VISA credit card, or to upload the
  473.           registration form to the BBS, call SpeedSoft Development,
  474.           Ben Morris, at
  475.                                    
  476.                Voice    (604) 472-0626
  477.                BBS      (604) 477-5337
  478.                         Modem settings: 8 Data, 1 Stop, No Parity
  479.                         Modem speed:    up to 14.400 baud, v.32.bis, v.42.bis
  480.                                                                                                                  
  481.      3)   By electronic mail: if this is by VISA or MASTERCARD
  482.           credit card, you can forward the information directly
  483.           to me by:
  484.  
  485.                Compuserve Mail at      100015,551
  486.                Internet                100015.551@compuserve.com
  487.                MHS                     MAIL@CSERVE {100015,551}
  488.  
  489.           North America only:
  490.  
  491.                CompuServe Mail at      72361,1552
  492.                Internet                72361.1552@compuserve.com
  493.                MHS                     MAILCSERVE {72361,1552}
  494.  
  495.      Check appendix D, page 43, for detailed information on how
  496.      to send email to Compuserve, and on how to obtain a Compu-
  497.      serve account.
  498.  
  499.      If registering with credit card your account will be char-
  500.      ged in Austrian funds (Austrian Schillings = ATS). You will
  501.      receive a confirmation by electronic mail or fax (if
  502.      available) when your order is processed.
  503.  
  504.  
  505. ----- DMalloc ------------------------------------------- Page 4 of 52 ------
  506.  
  507.  
  508.      Currency exchange will vary, but at the time of this ver-
  509.      sion's release 47.00 US$ was approximately:
  510.  
  511.           47.00 US$ (41+6s/h)ATS 479.40
  512.  
  513.      The registration fee licenses one copy of DMalloc for use
  514.      on any one computer at any one time.  You must treat this
  515.      software just like a book.  An example is that this softwa-
  516.      re may be used by any number of people and may be freely
  517.      moved from one computer location to another, as long as
  518.      there is no possibility of it being used at one location
  519.      while it's being used at another. Consider it like a book,
  520.      a book cannot be read by two different people at the same
  521.      time.
  522.  
  523.      For commercial users of DMalloc, site-license or multiple
  524.      license discount arrangements may be made by contacting the
  525.      author at the above address.
  526.  
  527.      If there is an unavoidable delay in registering, note that
  528.      DMalloc will continue to work unchanged after the evalua-
  529.      tion period. Under no circumstances will DMalloc do any
  530.      mischief to those who dishonestly continue to use DMalloc
  531.      without registering.
  532.  
  533. 1.7.1. Registering Your Evaluation Copy
  534.      DMalloc will be registered personally to you, i.e. your
  535.      serial number and your name will be shown at the top of the
  536.      screen (the Information Window, see section 5.3, page 22).
  537.      When you send in your registration, you will be provided a
  538.      registration number. You can use this registration number
  539.      together with the serialization utility to immediately re-
  540.      gister your DMalloc library and get rid of the shareware
  541.      reminder screens (DMSerial program, see appendix A, page
  542.      40, for more information).
  543.  
  544. 1.8. Distribution Policies
  545.      DMalloc(tm) and its documentation are COPYRIGHTED, and are
  546.      NOT PUBLIC DOMAIN.
  547.  
  548.      Anyone distributing DMalloc for any kind of direct fee must
  549.      first contact me at the address above for authorization.
  550.      Although authorization will generally be automatically
  551.      granted to distributors recognized by ASP as adhering to
  552.      its guidelines for shareware distributors ("associated ASP
  553.      members"), notification is still required.
  554.  
  555.      The above restriction does not apply to the case of normal
  556.      & usual connect charges on a BBS, where no other specific
  557.      charge is made for obtaining a copy of DMalloc.
  558.  
  559.      BBS Sysops
  560.      Please refer to the file SYSOP.DOC on the distribution
  561.      disk, or the uploaded ZIP file.
  562.  
  563.      Catalog and Disk Vendors
  564.      Please refer to the file VENDOR.DOC on the distribution
  565.      disk.
  566.  
  567.  
  568. ----- DMalloc ------------------------------------------- Page 5 of 52 ------
  569.  
  570.  
  571.      Individual users are encouraged to pass the "Unregistered
  572.      Evaluation Copy" of DMalloc along to their friends for eva-
  573.      luation.
  574.  
  575.      When secondarily distributed, DMalloc must be in its origi-
  576.      nal compressed form and accompanied by its full on-disk
  577.      documentation and other information files.  The distributed
  578.      software and documentation may not have been modified in
  579.      any way.
  580.  
  581.      No secondary distributor is authorized to accept registrations
  582.      for DMalloc. Registration fees may only be sent directly to
  583.      the author as outlined above in section 1.7, page 3.  Note
  584.      that the registration fee is exclusive of, and over and
  585.      above any fees that may be charged by a secondary distribu-
  586.      tor.
  587.  
  588.  
  589.  
  590. 1.9. Association of Shareware Professionals Ombudsman
  591.      The author is a member of the Association of Shareware Pro-
  592.      fessionals (ASP). ASP wants to make sure that the shareware
  593.      principle works for you.
  594.  
  595.      If you are unable to resolve a shareware-related problem
  596.      with an ASP member by contacting the member directly, ASP
  597.      may be able to help.  The ASP Ombudsman can help you resol-
  598.      ve a dispute or problem with an ASP member, but does not
  599.      provide technical support for members' products.  Please
  600.      write to:
  601.  
  602.           ASP Ombudsman
  603.           545 Grover Road, Muskegon
  604.           MI 49442
  605.           U.S.A.
  606.  
  607.      or send a CompuServe message via CompuServe Mail to
  608.           ASP Ombudsman 70007,3536
  609.  
  610.  
  611.  
  612.  
  613.  
  614.  
  615.  
  616.  
  617.  
  618.  
  619.  
  620.  
  621.  
  622.  
  623.  
  624.  
  625.  
  626.  
  627.  
  628.  
  629.  
  630.  
  631. ----- DMalloc ------------------------------------------- Page 6 of 52 ------
  632.  
  633.  
  634. 2. Installation
  635.  
  636. 2.1. From a Compressed Archive
  637.      If you received DMalloc as a compressed file (usually
  638.      DML100.ZIP (3)), please unpack the compressed file using
  639.      your favorite unzip utility. If you're using PKUnzip, type
  640.           
  641.           PKUNZIP DML100 [Enter]
  642.  
  643.      at the DOS command prompt. This will unpack the archive and
  644.      create the files as they are on the distribution disk. You
  645.      may unpack the archive either to a floppy disk, or directly
  646.      to your hard disk. After unpacking, proceed as if you re-
  647.      ceived a distribution disk.
  648.  
  649. 2.2. From a Distribution Disk
  650.      The distribution disk contains the following files:
  651.  
  652.           README                  | Information how to install DMalloc
  653.           FILE_ID.DIZ             | Information for automatic extraction
  654.                                   | by BBS software
  655.           PACKING.LST             | All files on the distribution disk
  656.           ASP.DOC                 | A notice about the ASP ombudsman
  657.           INSTALL.EXE             | The installation program (Z/Install)
  658.           INSTALL.LIB             | The installation archive
  659.  
  660.      Insert the distribution disk into any diskette drive (or
  661.      switch to the directory you copied the files to), and enter
  662.           INSTALL [Enter]
  663.  
  664.      This will start the installation program. Follow the in-
  665.      structions of the installation program to install DMalloc
  666.      to your system.
  667.  
  668. 2.3. Checking the Completed Installation
  669.      When the installation program finishes, you should have the
  670.      following files:
  671.  
  672.           README                  | Please read this!
  673.           PACKING.LST             | A list of all files in the package
  674.  
  675.           DMALLOC.LIB             | The actual DMalloc software
  676.           DMLNONE.LIB             | These files will be installed to the
  677.           DMALLOC.OBJ             |   directory as specified in the
  678.           DMALLOC7.OBJ            |   installation program
  679.           DMALLOC.H               |
  680.           DMALLOC.BC              |
  681.  
  682.           DMSERIAL.EXE            | unregistered shareware version only
  683.                                   |    to serialize the library
  684.                                   |    after registration
  685.           DMCONFIG.EXE            | registered version only
  686.                                   |    to configure the library to
  687.                                   |     your needs
  688.  
  689.  
  690.      ____________________
  691.  
  692.      3   The BBS distribution archive has been created using PKZip(tm).
  693.  
  694. ----- DMalloc ------------------------------------------- Page 7 of 52 ------
  695.  
  696.  
  697.           DOC\WARRANTY.DOC        | Important warranty information
  698.           DOC\REGISTER.FRM        | A form letter to register DMalloc
  699.           DOC\DESCRIBE.DOC        | A complete description of DMalloc
  700.           DOC\HISTORY.DOC         | DMalloc update history
  701.           DOC\VENDOR.DOC          | Important informations for
  702.                                   | shareware vendors
  703.           DOC\SYSOP.DOC           | Important information for BBS sysops
  704.           DOC\LASTINFO.DOC        | Last minute information
  705.           DOC\DMALLOC.DOC         | This documentation in ASCII format
  706.           DOC\SH-WARE.DOC         | Information on shareware, and computer
  707.                                   |    viruses
  708.           DOC\ASP.DOC             | Information about the ASP, its policy,
  709.                                   |    and the ASP Ombudsman
  710.           DOC\OMBUDSMN.DOC        | The ASP Ombudsman statement
  711.           DOC\PRESINFO            | Press information
  712.  
  713.           DOC\VIRUS.DOC           | registered version only
  714.                                   |    "Computer Virus Myths"
  715.                                   |    by Rob Rosenberger, Ross M. Greenberg
  716.  
  717.           SAMPLE\DEMO.BAT         | Batch and text file to start the demo
  718.           SAMPLE\DEMO.TXT         |
  719.           SAMPLE\DMLDEMO.EXE      | Disk version only (no BBS)
  720.                                   |    Ready to run demo program
  721.  
  722.           SAMPLE\MODULE1.C        | The demo program source files
  723.           SAMPLE\MODULE2.C        |
  724.           SAMPLE\MODULE3.C        |
  725.           SAMPLE\DMLDEMO.TXT      |
  726.           SAMPLE\DEMO.H           |
  727.           SAMPLE\MAKEFILE         | Make file for MSC 5.1 and 6+
  728.           SAMPLE\DMLDEMO.MAK      | MSC 7 PWB project file
  729.           SAMPLE\DMLDEMO.STS      | MSC 7 PWB session settings
  730.           SAMPLE\README           | Instructions how to build the demo program
  731.  
  732.  
  733. 2.4. Documentation
  734.  
  735. 2.4.1. Registration Form
  736.      REGISTER.FRM is the registration form you may use to regi-
  737.      ster DMalloc, or to request additional manuals. You may
  738.      print it by typing:
  739.  
  740.           COPY  REGISTER.FRM  PRN [Enter]
  741.  
  742.      To register, or to order a printed manual just fill it in,
  743.      and mail it (together with a check or money order) to the
  744.      address shown on the form. For additional information on
  745.      registering and the many benefits you'll receive, please
  746.      refer to section 1.7, page 3.
  747.  
  748.  
  749.  
  750.  
  751.  
  752.  
  753.  
  754.  
  755.  
  756.  
  757. ----- DMalloc ------------------------------------------- Page 8 of 52 ------
  758.  
  759.  
  760. 2.4.2. The Manual
  761.      DMALLOC.DOC is the installation, demo program and reference
  762.      documentation (this text). It contains no special format-
  763.      ting commands, can be viewed with any DOS text file viewer
  764.      or editor, and it should be printable on most any printer.
  765.  
  766.      To print, type at the DOS command line:
  767.  
  768.           COPY  DMALLOC.DOC  PRN [Enter]
  769.  
  770.      You should have at least 56 pages (4) of paper ready when
  771.      printing the manual. The documentation file includes "box
  772.      drawings", these use certain characters which may not be
  773.      available on some printers. Generally such printers replace
  774.      these special characters with italicised letters. If you
  775.      are able to, choose the "IBM mode" on such a printer.
  776.  
  777.      Don't let the thickness of the documentation scare you.
  778.      DMalloc is extremely easy to use. This manual will do its
  779.      best to teach you how to use DMalloc to debug your program.
  780.  
  781. 2.5. A Quick Start
  782.      To quickly get an existing program running with DMalloc,
  783.      relink the application together with the DMALLOC.OBJ (5)
  784.      object file. The DMALLOC.LIB library must be either in the
  785.      current directory or in one of the directories specified in
  786.      the LIB environment variable.
  787.      After linking, start the program as usual. DMalloc will pop
  788.      up before the main() function is called to allow you to
  789.      modify the setup options.
  790.  
  791.      Note: if an application is not compiled using the large memory
  792.            model (compiler directive -AL), the linker will issue an
  793.            error message and the program will not work. You must
  794.            compile the application using the large memory model (6).
  795.  
  796.  
  797.  
  798.  
  799.  
  800.  
  801.  
  802.  
  803.  
  804.  
  805.  
  806.  
  807.  
  808.  
  809.  
  810.  
  811.      ____________________
  812.  
  813.      4   The  size of the ASCII file  differs from the printed docu-
  814.          mentation due to different fonts and formatting
  815.      5   See  section 6.1.1, page  33, for  using different compiler
  816.          versions. For now, use DMALLOC.OBJ for  MSC 5.1 and MSC 6+,
  817.          and DMALLOC7.OBJ for MSC 7.
  818.      6   Future versions may support different memory models.
  819.  
  820. ----- DMalloc ------------------------------------------- Page 9 of 52 ------
  821.  
  822.  
  823. 2.6. Where to from here?
  824.      If you have never used DMalloc before, I would suggest that
  825.      you either run the demo program together with reading sec-
  826.      tion 3, page 10. To compile the demo program please refer
  827.      to section 3.1, page 12.
  828.  
  829.      If do not like a walkthrough approach to learning a program,
  830.      please study the reference sections:
  831.  
  832.           Section 3     is the walkthrough demonstration.
  833.           Section 4     describes dynamic memory, what may go wrong
  834.                         with it and what DMalloc does to catch tho-
  835.                         se bugs.
  836.           Section 5     describes the windows that appear in DMal-
  837.                         loc, and the use of the function keys.
  838.           Section 6     describes how to use DMalloc, and contains
  839.                         caveats with different compiler and linker
  840.                         versions.
  841.           Section 7     is the reference section for the DMalloc
  842.                         API.
  843.  
  844. 2.7. Support & Thanks
  845.      Questions, comments, suggestions, and even thanks are all
  846.      welcome. I am supporting this software via regular mail or
  847.      fax, or alternatively (this is preferred) on CompuServe,
  848.      either via electronic mail, or on the MSLANG forum, Micro-
  849.      soft C (3) section.
  850.  
  851.      Via CompuServe:
  852.           Address messages to my UserID 100015,551 through Compu-
  853.           Serve MAIL (GO MAIL at any CompuServe "!" prompt), or
  854.           leave a message for me in the CIS:MSLANG forum, Micro-
  855.           soft C (3) section (GO MSLANG at any CompuServe "!"
  856.           prompt).
  857.  
  858.      Via our Canadian support BBS:
  859.           SpeedSoft BBS, Home of Z/Install, The Fine Installation
  860.           Utility
  861.           Modem settings:         8 Data, 1 Stop, No Parity
  862.           Modem speed:            up to 14.400 baud, v.32.bis,
  863.                                   v.42.bis
  864.           Call:                   (604) 477-5337
  865.  
  866.      Via regular mail:
  867.           Forward all support questions to
  868.  
  869.           Ernest Vogelsinger
  870.           Hietzinger Hauptstrasse 40 c
  871.           A-1130 Vienna, Austria
  872.  
  873.      Via fax:
  874.           To send your questions, suggestions, etc, call
  875.  
  876.           (+43) 1 876 46 094      (international line)
  877.  
  878.  
  879.  
  880.  
  881.  
  882.  
  883. ----- DMalloc ------------------------------------------- Page 10 of 52 -----
  884.  
  885.  
  886.      For registered users, support is free for 6 (six) months
  887.      from date of registration. Email and CompuServe forum sup-
  888.      port continues to be free, whereas support via fax or regu-
  889.      lar mail will be charged US$ 10.-- per case. If the support
  890.      in question is of interest to all registered users, it will
  891.      be not be charged.
  892.  
  893.      Improved or new versions will be announced on CompuServe on
  894.      the MSLANG forum, Microsoft C (3) section, and on the SpeedSoft
  895.      BBS (see above). Registered users will be automatically notified
  896.      either via electronic mail, fax, or regular mail.
  897.  
  898.      My sincere thanks go out to all of those who have helped me
  899.      to improve DMalloc by offering up their wish lists, sugge-
  900.      stions and criticisms.
  901.  
  902.      Also a very special thanks to all the brave and tireless
  903.      BETA/GAMMA testers.
  904.  
  905.      Enjoy!
  906.  
  907.      Ernest Vogelsinger
  908.  
  909.  
  910.  
  911.  
  912.  
  913.  
  914.  
  915.  
  916.  
  917.  
  918.  
  919.  
  920.  
  921.  
  922.  
  923.  
  924.  
  925.  
  926.  
  927.  
  928.  
  929.  
  930.  
  931.  
  932.  
  933.  
  934.  
  935.  
  936.  
  937.  
  938.  
  939.  
  940.  
  941.  
  942.  
  943.  
  944.  
  945.  
  946. ----- DMalloc ------------------------------------------- Page 11 of 52 -----
  947.  
  948.  
  949. 3. The Demonstration Program
  950.  
  951.      The demonstration program consists of 3 files:
  952.           DEMO.BAT                | batch file to start the demo
  953.           DEMO.TXT                | text echoed by the batch file
  954.           DMLDEMO.EXE             | the actual demonstration program
  955.  
  956.      The demonstration program is a very simple C program that
  957.      prints text to the screen, allocates some memory, and con-
  958.      tains some nasty "bugs" to demonstrate the miscellaneous
  959.      features of DMalloc. The source files for the demo are in-
  960.      cluded as well:
  961.           MODULE1.C               | Main source file
  962.           MODULE2.C               | Additional modules
  963.           MODULE3.C               |
  964.           DMLDEMO.TXT             | Contains text printed on the screen
  965.           MAKEFILE                | MSC 5.1 makefile
  966.           DMLDEMO.MAK             | MSC 7 (PWB) project file
  967.           DMLDEMO.STS             | MSC 7 PWB session file
  968.  
  969. 3.1. Compiling the Demo Program
  970.      With MSC 5.1 and 6+, use the MAKEFILE make file to compile
  971.      the demo program. Please make sure that DMALLOC.LIB and
  972.      DMALLOC.H are either in the current directory, or available
  973.      in the LIB and INCLUDE paths.
  974.  
  975.      With MSC 7 PWB, use the DMLDEMO.MAK project file to compile
  976.      the demo project. For your convenience, the session set-
  977.      tings file is included (DMLDEMO.STS).
  978.  
  979. 3.2. Running the Demo
  980.      The demo program is not intended to cover the complete
  981.      functionality of DMalloc. It will give you an overview on
  982.      the basic features, the windows, and the integrity checks.
  983.  
  984.      Note: your monitor should be in text mode, and the display
  985.            width should be 80x25 or greater. If your primary
  986.            display is smaller (e.g.40x25), or a graphics mode is
  987.            active, DMalloc will either use an alternate monitor,
  988.            if available, or immediately quit with an appropriate
  989.            runtime error.
  990.  
  991.      To start the demo, type
  992.  
  993.           DEMO  [Enter]
  994.  
  995.      Since DMalloc pops up just before the main() function is
  996.      called (and before the demo can give you any explanation),
  997.      there is a batch file to help you at the very start. If you
  998.      typed DMLDEMO instead of DEMO, you are not really missing
  999.      anything, except the batch file telling you to press [F5]
  1000.      to start the demo.
  1001.  
  1002.  
  1003.  
  1004.  
  1005.  
  1006.  
  1007.  
  1008.  
  1009. ----- DMalloc ------------------------------------------- Page 12 of 52 -----
  1010.  
  1011.  
  1012. 3.3. DMalloc Startup
  1013.      Have a look at the screen now. On top you should see the
  1014.      Information Window. This window will always be visible whe-
  1015.      never DMalloc pops up. Its title shows the version and li-
  1016.      cense number of DMalloc. The contents will always reflect
  1017.      why DMalloc popped up - now it says that it's about to
  1018.      initialize.
  1019.  
  1020.      The Setup Window in the center of the screen can be used to
  1021.      modify the configuration options. For now we'll keep them
  1022.      as they are.
  1023.  
  1024.      On the bottom of the screen the function keys are display-
  1025.      ed. This line always reflects the actual status of the
  1026.      function keys - if there is no action for a key, it will be
  1027.      empty. The keys available now are
  1028.  
  1029.           [F2] Colors   modify the window colors
  1030.           [F4] View     temporarily hide the DMalloc windows and
  1031.                         view the program screen
  1032.           [F5] Go!      close all open windows and continue
  1033.           [F6] Select   select the heap entries that will be
  1034.                         displayed when the Heap Entries Window
  1035.                         pops up
  1036.           [F10] Back    close the topmost window and continue with
  1037.                         the window below
  1038.  
  1039.           The [F5] and [F10] keys are always available.
  1040.  
  1041.      Remember, you are still before the execution of main() be-
  1042.      gins. To actually start the demo program press [F5] now.
  1043.  
  1044.      Now the demo program is allocating a bunch of memory. As in
  1045.      a "real-world" C program, different source modules issue
  1046.      calls to malloc(). Two of them have been compiled with
  1047.      DMalloc info enabled, and the third without (as third party
  1048.      code would generally be). While allocating, you will notice
  1049.      DMalloc popping up regularly to check the consistency of
  1050.      the heap.
  1051.  
  1052.      At any time you may use DMalloc to look at the heap. To
  1053.      interactively popup DMalloc, press [PrtSc].
  1054.  
  1055. 3.4. Heap Overview
  1056.      If you haven't already, Please press [PrtSc] now. As there
  1057.      is no heap problem the Information Window shows that you
  1058.      pressed [PrtSc]. Below you see the Heap Entries Window.
  1059.      That's the main window of DMalloc.
  1060.  
  1061.      The Heap Entries Window lists all memory units that have
  1062.      been allocated by the program (7), sorted by address. Use
  1063.      the [Up], [Down], [PgUp], [PgDn], [Home] and [End] keys to
  1064.      move through the list. Press [Enter] to view the contents
  1065.  
  1066.  
  1067.      ____________________
  1068.  
  1069.      7   except units  allocated with  halloc() since  they are  not
  1070.          part of the heap.
  1071.  
  1072. ----- DMalloc ------------------------------------------- Page 13 of 52 -----
  1073.  
  1074.  
  1075.      of a unit, or use the [F7] key to see the total heap status
  1076.      (see next section). If you are done, press [F5] to continue
  1077.      with the demo.
  1078.  
  1079. 3.5. Total Heap Status
  1080.      Available at any time by pressing [F7], this window tells
  1081.      you the total amount of used and free memory, the size of
  1082.      the biggest available unit (very much like the _memmax()
  1083.      function), and the biggest unit available from DOS (i.e.
  1084.      memory that has not yet been claimed by the runtime
  1085.      library).
  1086.  
  1087. 3.6. Detecting Heap Problems
  1088.      Please press [F5] now to continue. Now, the demo program
  1089.      will do some out-of-bound writes to the allocated units.
  1090.      What would happen in a "real-world" program cannot be
  1091.      predetermined since it depends very much on the actual
  1092.      memory layout at runtime, what the program would do next
  1093.      (regarding the heap), and much more. It could never cause
  1094.      any harm, it could destroy some data, it could hang the
  1095.      machine, or crash the operating system.
  1096.  
  1097.      With DMalloc checking the heap, these errors will immedia-
  1098.      tely be found. When DMalloc pops up you'll notice that the
  1099.      Information Window tells you that corrupted units have been
  1100.      detected. The bar in the Heap Entries Window will be
  1101.      positioned at the first corrupted unit. To quickly jump
  1102.      between corrupted units, use the [Left] and [Right] keys.
  1103.  
  1104.      Three types of problems are shown here:
  1105.  
  1106.      Trailing Corruption (the first unit): This is the most com-
  1107.      mon problem. It occurs whenever you write more to a unit
  1108.      than you have allocated. Under normal conditions (without
  1109.      DMalloc) this would overwrite the allocation info of the
  1110.      following unit.
  1111.  
  1112.      Odd/Even Corruption (the second unit): Although similar to
  1113.      the first case it would never cause any problem in a "real-
  1114.      world" program. When an odd-sized unit is allocated, the
  1115.      runtime library automatically expands the size by one byte
  1116.      to evenly align units. However, the unit size may have been
  1117.      calculated (e.g. using strlen()), and this one-byte over-
  1118.      write would cause a Trailing Corruption if the size was
  1119.      even!
  1120.  
  1121.      Leading Corruption (the third unit): This would destroy the
  1122.      allocation info of the unit itself. It may be caused by an
  1123.      overwrite of the preceding unit, or by a faulty negative-
  1124.      index calculation into the unit itself.
  1125.  
  1126.      Press [F5] to continue the demo when you're ready.
  1127.  
  1128.  
  1129.  
  1130.  
  1131.  
  1132.  
  1133.  
  1134.  
  1135. ----- DMalloc ------------------------------------------- Page 14 of 52 -----
  1136.  
  1137.  
  1138. 3.7. Invalid Pointer Warning
  1139.      Whenever the program passes invalid parameters to free(),
  1140.      realloc() and expand() DMalloc will inform you. The reason
  1141.      for that kind of error may be either uninitialized varia-
  1142.      bles, duplicate freeing of the same pointer, freeing poin-
  1143.      ters to non-allocated data, and much more. Since the free()
  1144.      function doesn't check anything (except NULL pointers), and
  1145.      simply writes to the allocation info (immediately preceding
  1146.      the memory location pointed to) this could harm data needed
  1147.      elsewhere.
  1148.  
  1149. 3.8. Determining Action, Setting Breakpoints
  1150.      Now press [F10] to step back to the Information Window.
  1151.      You'll notice two selection fields: "You can:" and "Break-
  1152.      point:". These selection fields are always present in the
  1153.      Information Window unless you have pressed [PrtSc]. Press
  1154.      [Space]  to scroll the options, and press [Tab] or [Enter]
  1155.      to switch between the fields.
  1156.  
  1157.      The "You can:" field offers the following possibilities:
  1158.  
  1159.           Discard:      since the pointer to be freed is invalid you
  1160.                         may discard the call to free().
  1161.  
  1162.           Exit program: this will immediately exit the debugged program
  1163.                         by a call to exit(). Any function specified for
  1164.                         atexit() or onexit() processing will be called.
  1165.  
  1166.           Continue:     normally continue the program.
  1167.                         Note: if you choose this option now, freeing
  1168.                               the invalid pointer may hang your machine!
  1169.  
  1170.      The "Breakpoints:" field offers the following possibili-
  1171.      ties:
  1172.  
  1173.           None:         no breakpoint will be set.
  1174.  
  1175.           SoftIce:      DMalloc will generate a SoftIce breakpoint
  1176.                         (see section 6.6.1, page 37). If you have SoftIce
  1177.                         loaded, try this option now.
  1178.  
  1179.           CodeView:     set a CodeView breakpoint.
  1180.  
  1181.           Int3:         Set an unspecified interrupt-3 breakpoint.
  1182.                         Interrupt 3 is generally used to set debugger
  1183.                         breakpoints.
  1184.  
  1185.      The breakpoints will activate the debugger at the statement
  1186.      after the function that caused DMalloc to pop up. In as-
  1187.      sembler, you'll see a statement like "ADD SP, +2". In sour-
  1188.      ce mode, you'll see the line containing the function call.
  1189.  
  1190.      After making your selections, press [F5] or [F10] to conti-
  1191.      nue.
  1192.  
  1193.  
  1194.  
  1195.  
  1196.  
  1197.  
  1198. ----- DMalloc ------------------------------------------- Page 15 of 52 -----
  1199.  
  1200.  
  1201. 3.9. Null Pointer Assignments
  1202.      DMalloc can check for null pointer assignments. The demo
  1203.      will now overwrite the first few bytes of the data segment.
  1204.      In a "real-world" program this would only be detected when
  1205.      the program finishes. DMalloc will detect it much earlier
  1206.      when it walks the heap.
  1207.      The same check is also available for far null pointers.
  1208.      Usually, far null assignments overwrite the interrupt ta-
  1209.      ble. When a far null assignment is detected, DMalloc will
  1210.      not only tell you, but also undo the changes!
  1211.  
  1212. 3.10. Fatal Heap Errors
  1213.      Although DMalloc detects heap overwrites, it cannot guaran-
  1214.      tee that the allocation info needed by the runtime library
  1215.      is not tampered with. Whenever the heap structure is com-
  1216.      pletely destroyed (and a non-DMalloc program would hang),
  1217.      it will tell you so and gracefully exit the program.
  1218.  
  1219.      The demo program will now destroy the heap completely and
  1220.      start to free the pointers it previously allocated. Next time
  1221.      it gets a chance DMalloc will detect the heap failure and
  1222.      allow controlled program exit.
  1223.  
  1224.  
  1225.  
  1226.  
  1227.  
  1228.  
  1229.  
  1230.  
  1231.  
  1232.  
  1233.  
  1234.  
  1235.  
  1236.  
  1237.  
  1238.  
  1239.  
  1240.  
  1241.  
  1242.  
  1243.  
  1244.  
  1245.  
  1246.  
  1247.  
  1248.  
  1249.  
  1250.  
  1251.  
  1252.  
  1253.  
  1254.  
  1255.  
  1256.  
  1257.  
  1258.  
  1259.  
  1260.  
  1261. ----- DMalloc ------------------------------------------- Page 16 of 52 -----
  1262.  
  1263.  
  1264. 4. Dynamic Memory and DMalloc
  1265.  
  1266. 4.1. Dynamic Memory Layout
  1267.      The C Runtime Library allocates dynamic memory by partitio-
  1268.      ning the heap into allocation units. Each unit is preceded
  1269.      by an information block containing the size and the alloca-
  1270.      tion status (used/free):
  1271.  
  1272.         ───┐ ┌───────────┐ ┌───────────
  1273.          ╦═╧═╧╤════════╦═╧═╧╤════════╦
  1274.          ║Info│Contents║Info│Contents║
  1275.          ╩════╧╤═══════╩════╧════════╩
  1276.                └ malloc() pointer
  1277.  
  1278.      Since the allocation information is used to link the single
  1279.      units this is very critical to the integrity of the dynamic
  1280.      heap. Any tampering with the contents of the information
  1281.      field will produce unpredictable results. Even though most
  1282.      heap corruptions are only off-by-one errors, they can ne-
  1283.      vertheless be dangerous.
  1284.  
  1285.  
  1286. 4.2. DMalloc and Dynamic Memory
  1287.  
  1288.         ───┐ ┌───────────────────┐ ┌─
  1289.          ╦═╧═╧╤═══╤════════╤═══╦═╧═╧╤
  1290.          ║Info│Dml│Contents│Dml║Info│
  1291.          ╩════╧═══╧╤═══════╧═══╩════╧
  1292.                    └ malloc() pointer
  1293.  
  1294.      Here's where DMalloc comes in - it copes with heap problems
  1295.      is two ways:
  1296.      ■    it surrounds any allocated unit with small buffers con-
  1297.           taining initialized data to track those off-by-some
  1298.           errors, and to provide that they don't really corrupt
  1299.           the heap (allocation overhead = 2x4 bytes)
  1300.      ■    it tracks all allocated units in a tag table to hold
  1301.           additional information about the unit (one tag table
  1302.           entry = 10 bytes):
  1303.      ■    it provides the source file name and the line number
  1304.           where the unit has been allocated
  1305.      ■    it allows to "mark" any unit so freeing, reallocating
  1306.           and expanding will let DMalloc pop up
  1307.      ■    it checks the parameters for free(), realloc() and ex-
  1308.           pand() calls
  1309.  
  1310.  
  1311.  
  1312.  
  1313.  
  1314.  
  1315.  
  1316.  
  1317.  
  1318.  
  1319.  
  1320.  
  1321.  
  1322.  
  1323.  
  1324. ----- DMalloc ------------------------------------------- Page 17 of 52 -----
  1325.  
  1326.  
  1327. 4.3. Tracking the Functions
  1328.      One of the most convenient features of DMalloc is that it
  1329.      automatically tracks calls to the malloc functions, even
  1330.      without recompiling the code. How does this work?
  1331.  
  1332.      On startup, before main() is called, DMalloc patches the
  1333.      entry points to the malloc functions. When they are called
  1334.      later, control will automatically be passed to the DMalloc
  1335.      code. The following functions will be tracked (8):
  1336.  
  1337.      ■    _fmalloc (this is where the malloc() label points to in
  1338.           the large memory model)
  1339.      ■    calloc
  1340.      ■    realloc
  1341.      ■    expand
  1342.      ■    _ffree (this is where the free() label points to in the
  1343.           large memory model
  1344.      ■    _nmalloc
  1345.      ■    _nfree
  1346.  
  1347.      These functions are referenced throughout the manual as
  1348.      "malloc functions". Calling one of them will automatically
  1349.      activate DMalloc.
  1350.  
  1351. 4.4. Checking the Heap
  1352.      DMalloc checks the heap by calling the compiler specific
  1353.      heap walk functions for the near and far heap, and tests
  1354.      the results against its tag table. Whenever a corrupted
  1355.      unit is detected it will pop up. This heap walk can only be
  1356.      done when DMalloc gets control:
  1357.      ■    one of the above functions is called
  1358.      ■    each time DMalloc pops up
  1359.      ■    using the DMalloc programming API
  1360.  
  1361.      Usually it is not necessary to check the heap on every call
  1362.      to a malloc function. The frequency of the automatic check
  1363.      can be changed at runtime in the Setup Window (see section
  1364.      5.4, page 19), or with the DMalloc API (see section 7, page
  1365.      32).
  1366.  
  1367.  
  1368.  
  1369.  
  1370.  
  1371.  
  1372.  
  1373.  
  1374.  
  1375.  
  1376.  
  1377.  
  1378.  
  1379.  
  1380.  
  1381.      ____________________
  1382.  
  1383.      8   The tracked functions are compiler  specific. These are the
  1384.          functions for MSC. See section 6.1.1, page 33 for  informa-
  1385.          tion about compiler versions.
  1386.  
  1387. ----- DMalloc ------------------------------------------- Page 18 of 52 -----
  1388.  
  1389.  
  1390. 4.5. Types of Heap Corruption
  1391.      A program can overwrite the allocation information fields
  1392.      in both directions: upwards, destroying the info field of
  1393.      successive ("trailing") units, or downwards, destroying its
  1394.      own ("leading") information field. DMalloc detects both
  1395.      kinds of errors. Refer also to section 5.6, page 27, Heap
  1396.      Entries Window.
  1397.  
  1398. 4.5.1. Lead Corruption
  1399.      Lead Corruption occurs when the allocation information
  1400.      field preceding the unit is destroyed. This may be caused
  1401.      by either faulty downward indexing at the corrupted unit
  1402.      itself, or by out-of-bounds writes to the preceding unit.
  1403.  
  1404. 4.5.2. Trail Corruption
  1405.      Trail corruption occurs when the allocation information
  1406.      field following the unit is destroyed. This is most likely
  1407.      caused by out-of-bounds writes to the unit.
  1408.  
  1409. 4.5.3. Odd/Even Problem
  1410.      Odd/Even corruption is a special case of Trail corruption.
  1411.      Regardless if the allocated size is even or odd, the malloc
  1412.      functions always pad the unit size to be even (9). Thus
  1413.      writing one byte more than allocated would never cause a
  1414.      problem, and would never be detected. DMalloc however cat-
  1415.      ches this kind of problem as well, since the size could be
  1416.      a calculated value, and the off-by-one access would cause a
  1417.      Trail Corruption if the size was even.
  1418.  
  1419. 4.5.4. Mavericks
  1420.      Mavericks are allocated units that DMalloc doesn't know
  1421.      about, but detects when walking the heap. Since there is no
  1422.      "legal" way of allocation bypassing DMalloc, the occurrance
  1423.      of Mavericks is a clear sign that stray pointers corrupted
  1424.      the heap. Mavericks will usually be found when DMalloc de-
  1425.      tects an unrecoverable heap failure, and thus would termi-
  1426.      nate the program.
  1427.  
  1428.  
  1429.  
  1430.  
  1431.  
  1432.  
  1433.  
  1434.  
  1435.  
  1436.  
  1437.  
  1438.  
  1439.  
  1440.  
  1441.  
  1442.  
  1443.  
  1444.  
  1445.      ____________________
  1446.  
  1447.      9   This grants  all allocated units  to be aligned at  an even
  1448.          address.
  1449.  
  1450. ----- DMalloc ------------------------------------------- Page 19 of 52 -----
  1451.  
  1452.  
  1453. 4.6. Null Pointer Assignments
  1454.      The C runtime library provides a way to detect Null pointer
  1455.      assignments at the end of the program. Since this is a bit
  1456.      late to tell where it could have happened, DMalloc checks
  1457.      the NULL region whenever it checks the heap (see section
  1458.      5.6.3, page 25 how to activate this feature). It will pop
  1459.      up whenever it detects a change in the contents of the NULL
  1460.      region.
  1461.      Note: the runtime library provides 40h bytes at the beginning of the
  1462.            data segment to allow for checking against Null pointer
  1463.            assignments. You may disable this feature to save data and code
  1464.            space by providing a "int _nullcheck(void);" function returning
  1465.            0 (10). In this case, the linker will not pull the constant NULL
  1466.            segment in, and DS:0 assignments are perfectly valid since it's
  1467.            the program's data. DMalloc is aware of this and disables the
  1468.            (near) Nullcheck feature.
  1469.  
  1470. 4.7. Far Null Pointer Assignments
  1471.      Compiling for far data, NULL pointers will not point to the
  1472.      data segment NULL region but to the interrupt table. As-
  1473.      signments to FAR NULL pointers normally hang the machine,
  1474.      since interrupt pointers are destroyed. DMalloc checks the
  1475.      FAR NULL region (see section 5.6.3, page 29, how to activa-
  1476.      te this feature). Whenever an unknown change (11) is
  1477.      detected, DMalloc will reset the contents of the interrupt
  1478.      table to a known state, and pop up.
  1479.      Note: This is not a "lifebelt". Since an interrupt may be called before
  1480.            DMalloc detects the change, it may still crash the machine (12).
  1481.  
  1482. 4.8. Watchpoints
  1483.      DMalloc provides a way to notify you whenever a specific
  1484.      allocation unit is to be reallocated, expanded, or freed.
  1485.      Marking an allocated unit (see section 5.6.3, page 29) sets
  1486.      a Watchpoint that will direct DMalloc to pop up whenever
  1487.      that unit is to be freed, expanded, or reallocated.
  1488.  
  1489. 4.9. Savepoints
  1490.      DMalloc can remember certain allocated units from one ses-
  1491.      sion to the next, where it may pop up when a remembered
  1492.      unit has been allocated. This is automatically done with
  1493.      corrupted units. Additionally you may specify Savepoints
  1494.      (see section 5.6.4, page 30) to be saved for the next ses-
  1495.      sion, similar to a corrupted unit.
  1496.      When DMalloc pops up because a remembered unit has just
  1497.      been allocated, it will tell if it has been a corrupted or
  1498.      a saved entry.
  1499.  
  1500.      
  1501.      ____________________
  1502.  
  1503.      10  This function must reside in the _TEXT segment. The
  1504.          function name depends on the runtime library; this is 
  1505.          what it's called in MSC.
  1506.      11  DMalloc will know when the operating system changes an  in-
  1507.          terrupt.
  1508.      12  Interrupts called frequently  are 08h and 1Ch  (timer), 09h
  1509.          and 16h (keyboard), 10h (video), 21h (DOS),  and some more.
  1510.          However, interrupts 00h  to 07h (the first  two paragraphs)
  1511.          are not frequently called.
  1512.  
  1513. ----- DMalloc ------------------------------------------- Page 20 of 52 -----
  1514.  
  1515.  
  1516. 5. DMalloc In Detail
  1517.  
  1518.      Regardless of the situation, two elements of the user in-
  1519.      terface will always be present when DMalloc is up: the
  1520.      Function Key display, and the Information Window.
  1521.  
  1522. 5.1. About DMalloc Windows
  1523.      DMalloc uses three window types:
  1524.      ■    Informational windows containing only text. You cannot
  1525.           scroll or modify data
  1526.      ■    Data entry windows. You may enter or modify data at
  1527.           various entry fields.
  1528.      ■    A Listbox-like window
  1529.  
  1530.      Three types of data entry fields are available:
  1531.      ■    Ascii data entry to enter text.
  1532.      ■    Numeric data entry to enter numeric values. You may use
  1533.           the [Space], [Plus], [Minus], or [Back] keys to let it
  1534.           count up or down.
  1535.      ■    Selection entry to select from certain available valu-
  1536.           es. Press the [Space] key, or the first letter of the
  1537.           selection of your choice (e.g. [C] to select "Conti-
  1538.           nue").
  1539.  
  1540.      After entering or changing data in an data entry window,
  1541.      you may confirm the changes by pressing [F5] or [F10], or
  1542.      undo them by pressing [Esc].
  1543.  
  1544. 5.2. Function Keys
  1545.      The available function keys are always displayed at the
  1546.      bottom of the screen.
  1547.  
  1548.      Keys that are always available:
  1549.  
  1550.      [F4]   View     Hide the DMalloc screen to show the screen of
  1551.                     the debugged program (if an alternate monitor
  1552.                     is used (see section 5.4.8, page 25), this key
  1553.                     is unavailable).
  1554.      [F5]   Go!      Close all open DMalloc windows (as if pressing
  1555.                     [F10]) and immediately continue the interrupted
  1556.                     program
  1557.      [F10]  Back    Close the topmost window and continue with the
  1558.                     next below. If data has been entered in the
  1559.                     active window, it is saved.
  1560.      [Esc]  Undo    Close the topmost window and continue with the
  1561.                     next below. If data has been entered in the
  1562.                     active window, changes are discarded.
  1563.  
  1564.  
  1565.  
  1566.  
  1567.  
  1568.  
  1569.  
  1570.  
  1571.  
  1572.  
  1573.  
  1574.  
  1575.  
  1576. ----- DMalloc ------------------------------------------- Page 21 of 52 -----
  1577.  
  1578.  
  1579.      Keys that open a window, or perform an action:
  1580.  
  1581.      [F2]           Setup Window
  1582.                     -> Colors Window
  1583.      [Shft]+[F2]    Repair unit
  1584.      [Ctrl]+[F2]    Repair all
  1585.      [F3]           Heap Entries Window
  1586.                     -> Dump Window
  1587.                        -> Edit Contents
  1588.      [F6]           Selection Window
  1589.      [F7]           Heap Status Window
  1590.      [F9]           Set/Clear Watchpoint
  1591.      [Space]        Toggle Watchpoint
  1592.      [Ctrl]+[F9]    Set Watchpoint at all visible units
  1593.      [Alt]+[F9]     Toggle Watchpoint at all visible units
  1594.      [Shft]+[F9]    Clear Watchpoints at all visible units
  1595.  
  1596.  
  1597. 5.3. Information Window
  1598.  
  1599. ╔╡ DMalloc 1.0 for MSC 5.1/6+ (c) 1990-1992 E.Vogelsinger (UNREGISTERED) ╞══╗
  1600. ║ DMalloc has detected a heap problem:                                      ║
  1601. ║ One or more allocated units have been overwritten.                        ║
  1602. ║ You can: Continue      Breakpoint: None                1 new heap problem ║
  1603. ╚═══════════════════════════════════════════════════════════════════════════╝
  1604.  
  1605.      The title bar shows the DMalloc version, the compiler mo-
  1606.      del, and the serial number.
  1607.  
  1608.      The window text describes the exact reason for DMalloc to
  1609.      pop up.
  1610.  
  1611.      If a new heap corruption is detected (i.e. corrupted en-
  1612.      tries that have not yet been displayed), the total number
  1613.      of the new detections is displayed in the lower right cor-
  1614.      ner.
  1615.  
  1616.      Two selection fields are present at the bottom:
  1617.  
  1618. 5.3.1. "You can" - Select the Next Action
  1619.      Continue        will continue the debugged program.
  1620.      Exit program    will exit the program as soon as you leave                         DMalloc.
  1621.      Discard action  will discard the action that caused DMalloc to pop up.
  1622.                      This choice is only available if
  1623.                      ■  an invalid pointer was passed to realloc() or free()
  1624.                      ■  a far pointer was passed to _nfree()
  1625.                      ■  a Watchpoint has matured (see section 4.8, page 20)
  1626.  
  1627.  
  1628.  
  1629.  
  1630.  
  1631.  
  1632.  
  1633.  
  1634.  
  1635.  
  1636.  
  1637.  
  1638.  
  1639. ----- DMalloc ------------------------------------------- Page 22 of 52 -----
  1640.  
  1641.  
  1642. 5.3.2. "Breakpoint:"
  1643.      This field can be used to set breakpoints to debuggers (see
  1644.      section 6.6, page 36).
  1645.      None      will not set any breakpoint
  1646.      SoftIce   generates a breakpoint for the Soft-ICE(tm) debugger
  1647.      CodeView  generates a breakpoint for the CodeView(r) debugger
  1648.      Int3      generates an unspecified INT 03h instruction
  1649.  
  1650.      Note: Both selection fields are only present if DMalloc automatically
  1651.            popped up. Pressing the [PrtSc] key to activate DMalloc is an
  1652.            asynchronous action. The state of the operating system or a
  1653.            debugger cannot be predicted at this moment, so it could be
  1654.            fatal if DMalloc would try to break into the debugger,
  1655.            or to exit the running program.
  1656.  
  1657.  
  1658. 5.4. Setup Window
  1659.  
  1660. ╔╡ Setup ╞════════════════════╗
  1661. ║                             ║
  1662. ║ Alert on problem : Yes      ║
  1663. ║ Popup on saved   : No       ║
  1664. ║ Cycles for popup : 0        ║
  1665. ║ Heap check cycles: 100      ║
  1666. ║ Popup for file              ║
  1667. ║           line   : 0        ║
  1668. ║ Startup screen   : Yes      ║
  1669. ║ Shutdown screen  : Yes      ║
  1670. ║ Alternate monitor: No       ║
  1671. ║ Number of handles: 5000     ║
  1672. ║                             ║
  1673. ╚═════════════════════════════╝
  1674.  
  1675.      The Setup Window allows to modify the behaviour of DMalloc
  1676.      at runtime. The Setup Window is always available by pres-
  1677.      sing [F2].
  1678.  
  1679.      All setup options will be permanently stored in the confi-
  1680.      guration file (see section 5.10, page 32).
  1681.  
  1682. 5.4.1. Alert on problem (Default: Yes)
  1683.      Specifies if DMalloc should pop up if heap corruption is
  1684.      detected. Entering "No" lets DMalloc keep quiet even if it
  1685.      detects newly corrupted allocation units. However, there
  1686.      are situations when DMalloc will pop up regardless of this
  1687.      switch:
  1688.      ■    DMalloc is about to initialize (except switched off,
  1689.           see section 5.4.6, page 24)
  1690.      ■    an unrecoverable heap failure has been detected
  1691.      ■    a unit that has been found corrupted during the last
  1692.           session has been allocated, and the "Popup on saved"
  1693.           switch (see section 5.4.2, page 24) is set to "Corrupt"
  1694.           or "Both"
  1695.      ■    a unit marked for save (see section 5.6.4, page 30) has
  1696.           been allocated, and the "Popup on saved" switch is set
  1697.           to "Saved" or "Both"
  1698.      ■    the popup cycle count has elapsed (see section 5.4.3,
  1699.           page 20)
  1700.  
  1701.  
  1702. ----- DMalloc ------------------------------------------- Page 23 of 52 -----
  1703.  
  1704.  
  1705.      ■    the source file/line specified as popup reason is exe-
  1706.           cuted (see section 5.4.5, page 24)
  1707.      ■    [PrtSc] has been pressed
  1708.      ■    the DML_Trigger() API function was executed (see sec-
  1709.           tion 7, page 32)
  1710.      ■    the program has finished, and DMalloc is about to shut-
  1711.           down (except switched off, see section 5.4.7, page 25)
  1712.  
  1713.      Regardless of this switch, a small "Please wait" sign will
  1714.      always pop up whenever DMalloc checks the heap.
  1715.  
  1716. 5.4.2. Popup on saved (Default: No)
  1717.      DMalloc remembers units that have been found corrupted, and
  1718.      those marked for save (see section 5.6.4, page 30) during
  1719.      the last debug session. You may selectively specify which
  1720.      units you want to monitor:
  1721.  
  1722.      No        disables this feature
  1723.      Corrupt   will pop up only for units that have been corrupted
  1724.                in the last session
  1725.      Saved     will pop up only for units marked for save in the
  1726.                last session
  1727.      Both      will popup for both types.
  1728.  
  1729. 5.4.3. Cycles for popup (Default: 0)
  1730.      Regardless of heap corruption, DMalloc can be directed to
  1731.      pop up after a certain number of calls to the malloc
  1732.      functions have been made. Specify 0 if you do not want cy-
  1733.      cled popup.
  1734.      Note: the internal cycle counter is reset to zero whenever
  1735.            DMalloc pops up.
  1736.  
  1737. 5.4.4. Heap check cycles (Default: 100)
  1738.      Specifies after how many calls to the malloc functions
  1739.      DMalloc will check heap integrity. Although heap checking
  1740.      is quite fast, it is not necessary on every call. Specify 0
  1741.      if you do not want any automatic checking.
  1742.      Note: the heap will be checked always before DMalloc pops up,
  1743.            regardless of this setting, or if an invalid parameter to
  1744.            realloc(), free(), or expand() is detected.
  1745.  
  1746. 5.4.5. Popup for file/line (Default: blank/0)
  1747.      Entering a source file name will direct DMalloc to pop up
  1748.      whenever a call to the malloc functions is made by this
  1749.      source file. Entering a line number will further restrict
  1750.      popup to this specific source line, line number 0 will al-
  1751.      low popup at any call from this file.
  1752.      Note: the source file in question must be compiled with DMalloc
  1753.            information to enable this feature. If a wrong file name
  1754.            or a line number that does not contain a call to the malloc
  1755.            functions is entered, DMalloc will not pop up, even if the
  1756.            line is executed.
  1757.  
  1758. 5.4.6. Startup screen (Default: Yes)
  1759.      Normally, DMalloc pops up at the beginning, just before
  1760.      calling main(). You may disable the Startup Window by spe-
  1761.      cifying "No".
  1762.  
  1763.  
  1764.  
  1765. ----- DMalloc ------------------------------------------- Page 24 of 52 -----
  1766.  
  1767.  
  1768. 5.4.7. Shutdown screen (Default: Yes)
  1769.      Normally, DMalloc pops up at the end, after the atexit() or
  1770.      onexit() functions have been called. You may disable the
  1771.      Shutdown Window by specifying "No".
  1772.  
  1773. 5.4.8. Alternate monitor (Default: No)
  1774.      You may use an alternate monitor for DMalloc by selecting
  1775.      "Yes". DMalloc will use the selected monitor when it pops
  1776.      up the next time.
  1777.      There are situations where DMalloc will use the alternate
  1778.      monitor regardless of this setting:
  1779.      ■    your program switched to graphics mode
  1780.      ■    your program switched to a text mode with a different
  1781.           horizontal or vertical resolution than at initializa-
  1782.           tion time
  1783.      If you do not have an alternate monitor, and DMalloc would
  1784.      require it, it will not pop up until the display is reset
  1785.      for DMalloc's needs.
  1786.      Note: if, at initialization time, the display is either in graphics
  1787.            mode, or the text mode resolution is below 80x25, DMalloc will
  1788.            exclusively use the alternate display. If, in that case, you
  1789.            do not have an alternate display, DMalloc will immediately
  1790.            terminate at startup, issuing an appropriate runtime error.
  1791.      Note: if you do not have an alternate monitor, or the the alternate
  1792.            monitor is exlusively used by DMalloc, this field will not
  1793.            be accessible.
  1794.  
  1795. 5.4.9. Number of handles (Default: 5000, Maximum: 10900)
  1796.      As mentioned in section 4.2 (page 14), DMalloc allocates a
  1797.      tag table to track the allocated units. This entry speci-
  1798.      fies the size of the tag table.
  1799.      As this value is needed only at initialization time, this
  1800.      field is not accessible later.
  1801.      Note: If DMalloc runs out of handles (more allocations than table
  1802.            entries), it will abort the program and issue an appropriate
  1803.            runtime error.
  1804.  
  1805.  
  1806.  
  1807.  
  1808.  
  1809.  
  1810.  
  1811.  
  1812.  
  1813.  
  1814.  
  1815.  
  1816.  
  1817.  
  1818.  
  1819.  
  1820.  
  1821.  
  1822.  
  1823.  
  1824.  
  1825.  
  1826.  
  1827.  
  1828. ----- DMalloc ------------------------------------------- Page 25 of 52 -----
  1829.  
  1830.  
  1831. 5.5. Colors Window
  1832.  
  1833. ╔╡ Window Colors ╞═════════════════════╗
  1834. ║                                      ║
  1835. ║ Notice       : 3E Frame  3F Contents ║
  1836. ║ Heap         : 3E Frame  30 Contents ║
  1837. ║ Dump         : 3E Frame  30 Contents ║
  1838. ║ Selection    : 3E Frame  38 Contents ║
  1839. ║ Status       : 3E Frame  31 Contents ║
  1840. ║ Color        : 3E Frame  30 Contents ║
  1841. ║ Setup        : 3E Frame  30 Contents ║
  1842. ║ Wait message : 3E Frame  30 Contents ║
  1843. ║ Function Keys:           70 Contents ║
  1844. ║                                      ║
  1845. ╚══════════════════════════════════════╝
  1846.  
  1847.      The Colors Window allows to customize the screen colors of
  1848.      DMalloc. It is available only from the Setup Window by
  1849.      pressing [F2].
  1850.  
  1851.      For each window there are two entries: for the window fra-
  1852.      me, and for the window contents (13). The fields are se-
  1853.      lection fields that can be scrolled by pressing the
  1854.      [Space], [Home], or [End] keys. To switch between the
  1855.      fields, press the [Enter] or the [Tab] key.
  1856.  
  1857.      DMalloc maintains two color tables, one for color and one
  1858.      for monochrome displays. The Colors Window will display the
  1859.      table for matching the active display type.
  1860.  
  1861.      The color options will be permanently stored in the confi-
  1862.      guration file (see section 5.10, page 32). After colors
  1863.      have been changed they will be reflected whenever a window
  1864.      comes "on top" again.
  1865.  
  1866.  
  1867.  
  1868.  
  1869.  
  1870.  
  1871.  
  1872.  
  1873.  
  1874.  
  1875.  
  1876.  
  1877.  
  1878.  
  1879.  
  1880.  
  1881.  
  1882.  
  1883.  
  1884.  
  1885.  
  1886.  
  1887.      ____________________
  1888.  
  1889.      13  Except for the function keys - they have no window frame.
  1890.  
  1891. ----- DMalloc ------------------------------------------- Page 26 of 52 -----
  1892.  
  1893.  
  1894. 5.6. Heap Entries Window
  1895.  
  1896. ╔╡ Heap entries ╞══════════════════════════════════════════════╗
  1897. ║▒Block▒▒▒▒▒▒▒▒▒▒▒▒▒▒Owner▒▒line▒▒▒▒Size▒▒▒▒▒▒▒Lead▒▒▒▒▒▒Trail▒║
  1898. ║ 44CA:B0FC      module1.c   175      86         OK         OK ║
  1899. ║ 44CA:B15C      module2.c    24      77         OK         OK ║
  1900. ║ 44CA:B1B4      52unknown            43         OK         OK ║
  1901. ║▒44CA:B1EA▒▒▒▒▒▒module1.c▒▒▒175▒▒▒▒▒▒86▒▒▒▒▒▒▒▒▒OK▒▒CORRUPTED▒║
  1902. ║ 44CA:B24A      module2.c    24      77         OK   ODD-EVEN ║
  1903. ║ 44CA:B2A2      52unknown            43         OK         OK ║
  1904. ║ 44CA:B2D8      module1.c   175      86         OK         OK ║
  1905. ║ 44CA:B338      module2.c    24      77         OK         OK ║
  1906. ║ 44CA:B390      52unknown            43  CORRUPTED         OK ║
  1907. ║ 44CA:B3C6      module1.c   175      86         OK         OK ║
  1908. ╚══════════════════════════════════════════════════════════════╝
  1909.  
  1910.      The Heap Entries Window displays a list of all allocated
  1911.      units. Usually, the Heap Window is always visible (14).
  1912.      If not, you may activate it by pressing [F3].
  1913.  
  1914.      You may scroll through the heap list using the [Up],
  1915.      [Down], [PgUp], [PgDn], [Home], and [End] keys. The current
  1916.      position in the list is marked by an inverted bar.
  1917.  
  1918.      Each line represents an allocated unit, or another part of
  1919.      the programs memory. As shown above, the display contains
  1920.      (from left to right)
  1921.      Block     the (far) address of the allocated unit. This ad-
  1922.                dress was returned by the malloc functions.
  1923.      Owner     the source file that allocated this unit. If the
  1924.                owning source has not been compiled with DMalloc
  1925.                information, "52unknown" is displayed.
  1926.      line      the source line if the owner file is available.
  1927.      Size      the allocated size in bytes.
  1928.      Lead      the status of the leading control block (see section 4.2,
  1929.                page 14). Possible values are:
  1930.                OK            the leading control block is OK
  1931.                CORRUPTED     the leading control block has been
  1932.                              overwritten
  1933.      Trail     the status of the trailing control block (see section 4.2,
  1934.                page 14). Possible values are:
  1935.                OK            the trailing control block is OK
  1936.                CORRUPTED     the trailing control block has been
  1937.                              overwritten
  1938.                ODD/EVEN      an off-by-one error on an odd-sized
  1939.                              unit has been detected (see section
  1940.                              3.6, page 12)
  1941.  
  1942.  
  1943.  
  1944.  
  1945.  
  1946.  
  1947.  
  1948.  
  1949.  
  1950.      ____________________
  1951.  
  1952.      14  Unless you stepped back to the Information Window by pressing [F10]
  1953.  
  1954. ----- DMalloc ------------------------------------------- Page 27 of 52 -----
  1955.  
  1956.  
  1957.      Other entries that may be visible belong to preallocated
  1958.      data space and the Far Null region:
  1959.  
  1960.      ║ 0000:0000                         256         OK       FAR_NULL ║
  1961.      ║ 2975:0000                        49984         OK       FAR_DATA ║
  1962.      ║ 35A9:0000                         5040         OK       FAR_BSS  ║
  1963.      ║ 36E4:0000                       13990         OK       _DATA    ║
  1964.      ║ 36E4:36A6                          538         OK       BSS      ║
  1965.      ║ 36E4:44B2                          190         OK       DMALLOC  ║
  1966.      ║ 46E5:0016                         1048         OK       STARTUP  ║
  1967.  
  1968.      FAR_NULL       The first 256 bytes of the interrupt table. As
  1969.                     a special feature for far pointers, DMalloc can
  1970.                     track Far Null Pointer assignments (see section
  1971.                     4.7, page 16). To have Far Null checking enab-
  1972.                     led, this entry must be "tagged" (see section
  1973.                     5.6.3, page 25).
  1974.      FAR_DATA       All pre-initialized data that doesn't fit into
  1975.                     the data segment. Listed for completeness.
  1976.      FAR_BSS        All non-initialized data that doesn't fit into
  1977.                     the data segment. Listed for completeness.
  1978.      _DATA          The data segment containing pre-initialized
  1979.                     data (15). DMalloc can track Null pointer
  1980.                     assignments (see section 4.6, page 20). To have
  1981.                     Null checking enables, this entry must be "tagged"
  1982.                     (see section 5.6.3, page 29).
  1983.      BSS            All non-initialized data belonging to the data segment.
  1984.                     Listed for completeness (16).
  1985.      DMALLOC        Memory allocated by DMalloc for its own purpose.
  1986.                     They are used for screen buffers and the allocation
  1987.                     tag table.
  1988.      STARTUP        Not present with with all compilers. Some units may be
  1989.                     allocated before DMalloc initializes. Usually they
  1990.                     contain a copy of the environment, and a bunch of
  1991.                     pointers. Listed for completeness.
  1992.  
  1993.      You may freely select which type of entries you want to
  1994.      see. Refer to section 5.7 (page 25), Selection Window.
  1995.  
  1996.  
  1997.  
  1998.  
  1999.  
  2000.  
  2001.  
  2002.  
  2003.  
  2004.  
  2005.  
  2006.  
  2007.      ____________________
  2008.  
  2009.      15  Actually the _DATA entry consists of four consecutive segments:
  2010.          NULL, _DATA, CONST, and MSG (MS-C). Since they all contain
  2011.          pre-initialized data they are gathered in this entry.
  2012.          They all belong to DGROUP and are addressed through the DS or
  2013.          SS register.
  2014.      16  Since the  BSS segment is part of DGROUP it has the same segment
  2015.          address as the _DATA entry.
  2016.  
  2017. ----- DMalloc ------------------------------------------- Page 28 of 52 -----
  2018.  
  2019.  
  2020. 5.6.1. Detecting Corrupted Entries
  2021.      Whenever DMalloc detects a problem it will pop up. Regard-
  2022.      less of the popup reason displayed in the Information Wind-
  2023.      ow, the heap is completely checked, and the number of newly
  2024.      found corruptions blinks in the Information Window (see
  2025.      section 5.3, page 22). Corrupted Entries are always dis-
  2026.      played in high-intensity color (refer to section 4.5, page 19,
  2027.      for different corruption types). When they are considered
  2028.      new (17) they will blink.
  2029.  
  2030.      You can quickly move between corrupted entries by pressing
  2031.      the [Left] or [Right] keys.
  2032.  
  2033.      An allocation unit that has been found corrupted will al-
  2034.      ways be saved in the configuration file (see sections 5.10,
  2035.      page 28, and 5.4.2, page 20).
  2036.  
  2037. 5.6.2. "Repairing" Corrupted Entries
  2038.      To clear the "corruption" marks at an entry, you can press
  2039.      [Shft]+[F2] to repair the currently active unit, or
  2040.      [Ctrl]+[F2] to repair all.
  2041.      Repairing units will reset the corruption flags, and also
  2042.      reset the contents of the surrounding control blocks (see
  2043.      section 4.2, page 17).
  2044.      Repairing  NULLCHECK at the _DATA entry will not reset the
  2045.      contents of the Null region but only clear the corruption
  2046.      flag.
  2047.      Repairing NULLCHECK at the FAR_NULL entry will only clear
  2048.      the corruption flag. The contents of the Far Null region
  2049.      are automatically reset whenever this type of corruption is
  2050.      encountered.
  2051.      Note:     when repairing a corrupted unit, DMalloc will reset
  2052.                the control block contents. If the program relies
  2053.                on these contents (outside of the allocated unit)
  2054.                don't repair but exit the program and correct the
  2055.                error.
  2056.      Note:     Having repaired a unit, it will not be remembered
  2057.                (see section 5.10, page 32).
  2058.  
  2059. 5.6.3. Watchpoints ("Tags")
  2060.      Watchpoints are used to activate DMalloc whenever a watched
  2061.      unit is to be freed, reallocated, or expanded (see section
  2062.      4.8, page 17). Setting a Watchpoint on the FAR_NULL or _DA-
  2063.      TA segment will enable checking for Null pointer as-
  2064.      signments.
  2065.      Active Watchpoints are displayed as "Tags" () at the wat-
  2066.      ched entry.
  2067.  
  2068.  
  2069.  
  2070.  
  2071.  
  2072.  
  2073.  
  2074.  
  2075.      ____________________
  2076.  
  2077.      17  A heap corruption is considered new until it has been shown
  2078.          the first time.
  2079.  
  2080. ----- DMalloc ------------------------------------------- Page 29 of 52 -----
  2081.  
  2082.  
  2083.      You can quickly move between tagged entries by pressing the
  2084.      [Ctrl]+[Left] or [Ctrl]+[Right] keys.
  2085.  
  2086.      To set or clear Watchpoints, press
  2087.      [F9]           or [T]        to tag an entry
  2088.      [F9]           or [U]        to untag an entry
  2089.      [Space]                      to toggle one tag
  2090.      [Ctrl]+[F9]    or [Ctrl]+[T] to tag all entries
  2091.      [Alt]+[F9]                   to toggle all tags
  2092.      [Shft]+[F9]    or [Ctrl]+[U] to untag all entries
  2093.  
  2094. 5.6.4. Savepoints
  2095.      DMalloc remembers allocation units between debug sessions
  2096.      (see section 4.9, page 20). This is done automatically for
  2097.      corrupted units. Optionally, you may specify some units to
  2098.      be saved by simply pressing [S]. Whenever DMalloc allocates
  2099.      a saved unit again it will pop up.
  2100.      Unlike remembering a corrupted unit, a Savepoint is sticky,
  2101.      i.e. you have to clear it by pressing [S] or it will be
  2102.      kept for that unit (as long as the unit keeps being allocated).
  2103.      Active Savepoints are displayed with an 'S' at the entry.
  2104.  
  2105. 5.7. Selection Window
  2106.  
  2107. ╔╡ Select ╞════════════════════════╗
  2108. ║                                  ║
  2109. ║  Allocated units :  Yes          ║
  2110. ║  Marked only     :  No           ║
  2111. ║  Nullptr. areas  :  Yes          ║
  2112. ║  Data segments   :  No           ║
  2113. ║  System entries  :  No           ║
  2114. ║  Owner file      :               ║
  2115. ║        line      :  0            ║
  2116. ║                                  ║
  2117. ╚══════════════════════════════════╝
  2118.  
  2119.      The Selection Window selects which entries will be display-
  2120.      ed in the Heap Entries Window. It is available only from
  2121.      the Heap Entries Window by pressing [F6]. Changing the se-
  2122.      lection will immediately be reflected by the Heap Entries
  2123.      Window.
  2124.  
  2125.      Allocated Units (Default: Yes)
  2126.           Selects all allocated units except those marked DMALLOC
  2127.           and STARTUP.
  2128.  
  2129.      Marked only (Default: No)
  2130.           If Yes, only entries that are currently tagged or mar-
  2131.           ked for save will be shown.
  2132.  
  2133.      Nullptr. areas (Default: Yes)
  2134.           If Yes, the FAR_NULL and _DATA entries will be shown.
  2135.  
  2136.      Data segments (Default: No)
  2137.           If Yes, all data segments (FAR_NULL, FAR_DATA, FAR_BSS,
  2138.           _DATA, BSS) will be shown.
  2139.           If No, the FAR_NULL and _DATA segments may be shown
  2140.           when "Nullptr areas" is "Yes".
  2141.  
  2142.  
  2143. ----- DMalloc ------------------------------------------- Page 30 of 52 -----
  2144.  
  2145.  
  2146.      System entries (Default: No)
  2147.           If Yes, DMALLOC and STARTUP entries will be shown.
  2148.  
  2149.      Owner file/line (Default: blank/0)
  2150.           If a source file is entered here, only those entries
  2151.           belonging to the specified source file/line will be
  2152.           shown.
  2153.  
  2154. 5.8. Dump Window
  2155.  
  2156. ╔╡ Dump 36E4:0000 ╞════════════════════════════════════════════════════════╗
  2157. ║ 36E40:  00 00 00 00 00 00 00 00-4D 53 20 52 75 6E 2D 54 ........MS Run-T ║
  2158. ║ 36E50:  69 6D 65 20 4C 69 62 72-61 72 79 20 2D 20 43 6F ime Library - Co ║
  2159. ║ 36E60:  70 79 72 69 67 68 74 20-28 63 29 20 31 39 39 30 pyright (c) 1990 ║
  2160. ║ 36E70:  2C 20 4D 69 63 72 6F 73-6F 66 74 20 43 6F 72 70 , Microsoft Corp ║
  2161. ║ 36E80:  00 00 00 00 00 00 00 00-00 00 00 00 00 00 00 00 ................ ║
  2162. ║ 36E90:  00 00 00 00 00 00 00 00-00 00 00 00 00 00 00 00 ................ ║
  2163. ╚══════════════════════════════════════════════════════════════════════════╝
  2164.  
  2165.      The Dump Window allows you to view and edit the contents of
  2166.      a memory unit. It is available from the Heap Entries Window
  2167.      by pressing [F3] or [Enter].
  2168.  
  2169.      The Window Title displays the unit address. The contents
  2170.      are shown in hex and ASCII format. The column to the far
  2171.      left shows the (incrementing) 20-bit address (18).
  2172.  
  2173.      The size of the Dump Window may vary, depending on the ac-
  2174.      tual size of the memory unit. The maximum size (as shown
  2175.      above) is 16 paragraphs (or 256 bytes). If the size of the
  2176.      unit is bigger you may scroll the Dump Window using the
  2177.      [Up], [Down], [PgUp], [PgDn], [Home], and [End] keys.
  2178.  
  2179.  
  2180. 5.8.1. Editing Data
  2181.      Press [F3] to edit the Dump Window contents. When in Edit
  2182.      mode, a block cursor appears at the location where data is
  2183.      to be modified. Using the [Tab] key you can toggle between
  2184.      Hex Mode and Ascii Mode. Use the [Up], [Down], [Left],
  2185.      [Right], [Home], and [End] keys to move the cursor.
  2186.      Modified data will be displayed in high intensity color.
  2187.      Pressing [F5] or [F10] will write the modified data back,
  2188.      pressing [Esc] will ignore the changes.
  2189.  
  2190.      Note: Edit Mode is not available at the memory units marked FAR_NULL
  2191.            and DMalloc, since their contents are critical to the system.
  2192.      Note: Modifying the _DATA unit between offset 00h and offset 40h will
  2193.            result in a NULLCHECK warning and the appropriate runtime error
  2194.            at program termination (Null pointer assignment).
  2195.  
  2196.  
  2197.  
  2198.  
  2199.  
  2200.      ____________________
  2201.  
  2202.      18  In Real Mode, the highest memory address available is FFFF:FFFF,
  2203.          or as absolute address 10FFEF. It needs 21 bits to form this
  2204.          number. However, this address should never be a malloc unit.
  2205.  
  2206. ----- DMalloc ------------------------------------------- Page 31 of 52 -----
  2207.  
  2208.  
  2209. 5.9. Heap Status Window
  2210.  
  2211. ╔╡ Heap Status ╞════════════════╗
  2212. ║             Blocks      Bytes ║
  2213. ║────────────────────┬──────────║
  2214. ║                    │          ║
  2215. ║ Allocated:      10 │      170 ║
  2216. ║ Free     :       2 │    34384 ║
  2217. ║    biggest on heap │    32776 ║
  2218. ║    biggest in DOS  │   212704 ║
  2219. ║                    │          ║
  2220. ╚═══════════════════════════════╝
  2221.  
  2222.      The Heap Status Window is available at any time by pressing
  2223.      [F7]. The following information is presented:
  2224.      Allocated          the number of units currently allocated, and the
  2225.                         memory size occupied by them.
  2226.      Free               the number of free units currently available within
  2227.                         near and far heap, and the total size of all free
  2228.                         units.
  2229.                         Note: DMalloc calculates neighboring free units
  2230.                               as one.
  2231.      biggest on heap    the size of the biggest free unit in bytes (19).
  2232.      biggest in DOS     the biggest contiguous memory block currently
  2233.                         available from DOS (20).
  2234.  
  2235.  
  2236. 5.10. The Configuration File
  2237.      All options from the Setup, Colors, and Selection Window
  2238.      are permanently stored in a configuration file. The name of
  2239.      the configuration file will be the same name as the name of
  2240.      the debugged EXE file, with extension .DMC (21). If, by
  2241.      chance, there is another file with the same name, DMalloc
  2242.      will not attempt to read its contents at initialization
  2243.      time, and will not overwrite it when terminating.
  2244.  
  2245.      All allocated units that have been found corrupted are sto-
  2246.      red in the configuration file, even if they have been freed
  2247.      or reallocated again. Also units marked 'S' for save will
  2248.      be stored.
  2249.  
  2250.      DMalloc tries to be clever when storing pointers. Since the
  2251.      program can be loaded anywhere in memory the segment portion
  2252.      of pointers will not necessarily be the same the next time you
  2253.      run it. For this reason the segment portion of the pointer is
  2254.      somehow normalized. However, if the size of the data segments
  2255.      has changed, or the allocation sequence is different, there is
  2256.      no way for DMalloc to detect when saved pointers are allocated,
  2257.      since they may be located somewhere else.
  2258.  
  2259.  
  2260.      ____________________
  2261.  
  2262.      19  The similar _memmax() function reports on the near heap only.
  2263.          DMalloc reports on both near and far heap.
  2264.      20  The total size of free memory may vary from the maximum size,
  2265.          depending on the respective environment.
  2266.      21  For example, for a TEST.EXE program, DMalloc would create a
  2267.          TEST.DMC configuration file.
  2268.  
  2269. ----- DMalloc ------------------------------------------- Page 32 of 52 -----
  2270.  
  2271.  
  2272. 5.10.1. Configuring the Library
  2273.      If you have the registered version of DMalloc you may use
  2274.      the DMConfig utility program to modify the Setup, Colors,
  2275.      and Selection settings in the DMalloc library directly.
  2276.      Please refer to appendix B, page 41, for information about
  2277.      DMConfig.
  2278.  
  2279.  
  2280. 6. How to use DMalloc
  2281.  
  2282.      There are different levels of integration into the debugged
  2283.      program:
  2284.      ■    You may simply link DMalloc to the program, recompile
  2285.           part of, or all, source code.
  2286.      ■    Do the above -plus- call the DMalloc API functions from
  2287.           within the program.
  2288.  
  2289. 6.1. Linking DMalloc to the Program
  2290.      This is the most simple way to integrate DMalloc. Relink
  2291.      the program with an additional object, DMALLOC.OBJ. You do
  2292.      not need to specify the DMALLOC.LIB library to the linker
  2293.      as long as it can be found in one of the directories
  2294.      specified in the LIB environment variable.
  2295.  
  2296.      This will integrate the whole DMalloc functionality except
  2297.      that DMalloc cannot know where units are allocated.
  2298.  
  2299. 6.1.1. Using Different Compilers
  2300.      DMalloc is prepared to support different compilers and Run-
  2301.      time Libraries. The compiler and library specific data and
  2302.      code is located in the external object file you link with
  2303.      your program.
  2304.  
  2305.      Currently available are:
  2306.           MSC 5.1, 6+   DMALLOC.OBJ
  2307.           MSC 7         DMALLOC7.OBJ
  2308.  
  2309.      The Information Window will show for which compiler you
  2310.      have linked the program. Please make sure that you're al-
  2311.      ways using the correct object file.
  2312.  
  2313. 6.1.2. Using Overlay Linkers
  2314.      You may use DMalloc with any overlay linker. However, there
  2315.      are a few precautions that must be kept in mind:
  2316.      ■    Always link the DMALLOC.OBJ file to the main program
  2317.           file. DMalloc cannot be overlaid.
  2318.      ■    If the linker allows to overlay runtime library
  2319.           functions, keep all functions of the malloc group within
  2320.           the main program.
  2321.  
  2322.  
  2323.  
  2324.  
  2325.  
  2326.  
  2327.  
  2328.  
  2329.  
  2330.  
  2331.  
  2332. ----- DMalloc ------------------------------------------- Page 33 of 52 -----
  2333.  
  2334.  
  2335. 6.2. Recompiling
  2336.      If you want to know which source file allocated which
  2337.      units, you may recompile the source files where the malloc
  2338.      functions are called.
  2339.  
  2340.      First, define the _DMALLOC switch. You may either add
  2341.  
  2342.           -D_DMALLOC
  2343.  
  2344.      to the compiler directive in the make file, or add the line
  2345.  
  2346.           #define _DMALLOC
  2347.  
  2348.      to the source file.
  2349.  
  2350.      Next, include DMALLOC.H into the source by adding the fol-
  2351.      lowing line to the source file:
  2352.  
  2353.           #include <DMALLOC.H>
  2354.  
  2355.      Third, recompile the source, and link the program as speci-
  2356.      fied above. You still need DMALLOC.OBJ to be linked to the
  2357.      program.
  2358.  
  2359.      Note: DMALLOC.H must be included after the standard C include
  2360.            files (STDDEF.H, STDLIB.H).
  2361.      Note: The switch _DMALLOC needs to be defined before DMALLOC.H
  2362.            is included.
  2363.  
  2364. 6.2.1. Effects and Side-Effects when using the _DMALLOC switch
  2365.      When you activate the _DMALLOC switch as outlined above,
  2366.      some sections in the DMALLOC.H include file are activated.
  2367.      This is what will happen:
  2368.      ■    Access to the API is granted. If the switch is undefi-
  2369.           ned all references to DMalloc API functions are resol-
  2370.           ved with empty statements.
  2371.      ■    The malloc group functions are redefined to point to
  2372.           DMalloc's function replacements (22). Each time you
  2373.           call a malloc function, the file name and line number
  2374.           information will be inserted into the code.
  2375.  
  2376.      Inserting the file name information is done by using the
  2377.      __FILE__ macro (this is how it is called with MSC). Unfor-
  2378.      tunately this will increase the size of the EXE file since
  2379.      it adds the complete file name each time you use it.
  2380.  
  2381.  
  2382.  
  2383.  
  2384.  
  2385.  
  2386.  
  2387.  
  2388.  
  2389.  
  2390.      ____________________
  2391.  
  2392.      22  Actually the functions are not replacements but prefixes that
  2393.          call the original runtime library functions later.
  2394.  
  2395. ----- DMalloc ------------------------------------------- Page 34 of 52 -----
  2396.  
  2397.  
  2398.      There is a workaround you may use to keep the compiler from
  2399.      adding the file name multiple times:
  2400.  
  2401.           #define _DMALLOC                   /* activate the DMalloc API */
  2402.  
  2403.           #define __DMFILE__                 /* define to use the single */
  2404.           static char * DM_file$ = __FILE__; /* file name char constant  */
  2405.  
  2406.           #include <dmalloc.h>               /* include the file         */
  2407.  
  2408.  
  2409.      By defining the __DMFILE__ switch the include file will use
  2410.      the static (23) character constant DM_file$ instead of
  2411.      repeatedly placing the __FILE__ macro.
  2412.  
  2413.      Due to the nature of the __FILE__ macro you cannot put the-
  2414.      se statements into an include file. It would always retrie-
  2415.      ve the name of the include file, not of the source file.
  2416.  
  2417. 6.3. Calling the DMalloc API
  2418.      DMalloc provides API functions that can be called from the
  2419.      program (see section 7, page 38). The API functions allow
  2420.      to let DMalloc check the heap, popup DMalloc, temporarily
  2421.      or permanently modify the setup, set watchpoints or save-
  2422.      points on pointers, generate debugger breakpoints, and to
  2423.      disable or enable DMalloc for special purposes. Please see
  2424.      the API reference for detailed discussion.
  2425.  
  2426. 6.4. DMalloc and Spawn
  2427.      All exec.., spawn... and system() calls can be used together
  2428.      with DMalloc. Dmalloc will automatically detect when another
  2429.      process is being executed, and disable itself.
  2430.  
  2431. 6.5. DMalloc and Video
  2432.      DMalloc is compatible with the RLSI (Relocatable Screen
  2433.      Interface) specification. If you have installed a DOS memo-
  2434.      ry manager (e.g. DesqView(r), or Memory Commander(r)) that
  2435.      relocates the video buffer, DMalloc will continue to work.
  2436.      Note: If your program accesses the video buffer directly,
  2437.            it also needs to adhere to the RLSI standard, since
  2438.            the RLSI host will not trap and relocate "standard"
  2439.            video buffer accesses after RLSI has been initialized.
  2440.            Please read the next two sections about the
  2441.            RLSI specification.
  2442.  
  2443.  
  2444.  
  2445.  
  2446.  
  2447.  
  2448.  
  2449.  
  2450.  
  2451.      ____________________
  2452.  
  2453.      23  Do not forget to make that variable  static! Otherwise you would
  2454.          only have one global symbol in the EXE file, and only see the name
  2455.          of the last linked object file, since the linker will treat it
  2456.          as a common variable.
  2457.  
  2458. ----- DMalloc ------------------------------------------- Page 35 of 52 -----
  2459.  
  2460.  
  2461. 6.5.1. The Relocatable Screen Interface (RLSI)
  2462.      Some memory managers (e.g. Memory Commander(r)), or multi-
  2463.      tasking programs (e.g. DesqView(r)), relocate (parts of)
  2464.      the video memory to make more memory available to DOS. Pro-
  2465.      grams that use the default video frames (0xB800 for color,
  2466.      and 0xB000 for monochrome) for direct video writes will
  2467.      still work with these environments but will run a lot slo-
  2468.      wer than necessary, since the RLSI host must use an excep-
  2469.      tion mechanism to transfer the video access.
  2470.  
  2471.      Any program that uses direct video I/O should therefore
  2472.      call the RLSI interface before the first video access. The
  2473.      interface function is entered with a far pointer to the
  2474.      assumed video buffer (usually 0xB800:0 or 0xB000:0), and
  2475.      will return a valid far pointer to the relocated memory
  2476.      location. Additionally, calling the interface function will
  2477.      speed up video I/O, since the RLSI host assumes that the
  2478.      client knows about the relocation, and will not trap the
  2479.      old video locations.
  2480.  
  2481.      The shortcoming is: if you once call RLSI, direct I/O to
  2482.      the old video buffer will no longer be visible. You must use
  2483.      the pointer returned by RLSI.
  2484.  
  2485. 6.5.2. Calling RLSI
  2486.      RLSI is called via interrupt 10h (video interrupt).
  2487.  
  2488.          union  REGS  regs;
  2489.          struct SREGS sregs;
  2490.  
  2491.          regs.x.ax  = 0xFE00;       /* RLSI function code           */
  2492.          regs.x.di  = ofsVPage;     /* video page offset, usually 0 */
  2493.          sregs.es   = segVBuffer;   /* video buffer                 */
  2494.                                     /* (usually 0xB800 or 0xB000)   */
  2495.          int86x(0x10, ®s, ®s, &sregs);
  2496.  
  2497.          ofsVPage   = regs.x.di;    /* get the RLSI values          */
  2498.          segVBuffer = sregs.es;
  2499.  
  2500. 6.6. DMalloc and Debuggers
  2501.      DMalloc allows you to set debugger breakpoints. Whenever
  2502.      DMalloc pops up (except when [PrtSc] has been pressed) you
  2503.      may direct it to set a debugger breakpoint (see section 5.3.2,
  2504.      19). The debugger will receive control at the statement im-
  2505.      mediately following the call to the malloc function (i.e.
  2506.      in your code instead of code belonging to the runtime
  2507.      library, or DMalloc).
  2508.  
  2509.  
  2510.  
  2511.  
  2512.  
  2513.  
  2514.  
  2515.  
  2516.  
  2517.  
  2518.  
  2519.  
  2520.  
  2521. ----- DMalloc ------------------------------------------- Page 36 of 52 -----
  2522.  
  2523.  
  2524. 6.6.1. Soft-ICE(tm)
  2525.      Soft-ICE is a resident protected-mode debugger from Nu-Mega
  2526.      Technologies, Inc. It can be used to debug operating system
  2527.      code, high frequent interrupt code, TSR programs, and much
  2528.      more.
  2529.      Soft-ICE breakpoints are sticky. When Soft-ICE gets control
  2530.      you will see a message like this:
  2531.           Breakpoint generated by DMalloc (remove with BC 0)
  2532.      If you do not clear that breakpoint, Soft-ICE will always
  2533.      pop up at the very same location.
  2534.      Note:     It will do no harm trying to set a Soft-ICE break-
  2535.                point without having Soft-ICE loaded.
  2536.  
  2537. 6.6.2. CodeView(r)
  2538.      Contrary to a Soft-ICE breakpoint, CodeView breakpoints are
  2539.      not sticky. CodeView will get control at the statement af-
  2540.      ter the malloc function call, but no permanent breakpoint
  2541.      will be set.
  2542.      Note:     It will do no harm trying to set a CodeView break-
  2543.                point without running CodeView.
  2544.  
  2545. 6.6.3. Other Debuggers
  2546.      Every debugger will get control when interrupt 03h is exe-
  2547.      cuted. DMalloc provides that unspecific method for other
  2548.      debuggers.
  2549.      Note:     Most CodeView versions will also get control at
  2550.                this type of breakpoint, Soft-ICE will not by de-
  2551.                fault.
  2552.  
  2553. 6.7. DMalloc and Bounds-Checker(r)
  2554.      Bounds-Checker is a 386-based utility to detect out-of-
  2555.      bounds memory accesses while running a DOS program. It gi-
  2556.      ves the same type of memory protection as a protected mode
  2557.      operating system. DMalloc and Bounds-Checker are ideal com-
  2558.      panions. You can use Bounds-Checker to verify segment-based
  2559.      integrity, and DMalloc to assure the integrity of the heap
  2560.      contents.
  2561.      Bounds-Checker can be directed to allow access to memory
  2562.      locations that are protected by default (24) by specifying
  2563.      exceptions in an exception file. Since DMalloc accesses
  2564.      some restricted locations, Bounds-Checker must know about
  2565.      it or it would complain. An exception file for Bounds-
  2566.      Checker comes with the DMalloc package (DMALLOC.BC). Simply
  2567.      copy the contents of this file to your exception file, and
  2568.      Bounds-Checker will accept the liberties DMalloc takes.
  2569.  
  2570.  
  2571.  
  2572.  
  2573.  
  2574.  
  2575.  
  2576.  
  2577.  
  2578.      ____________________
  2579.  
  2580.      24  Typical candidates for  exceptions are the code  segment for
  2581.          routines written in  assembler, the Bios area  beginning at
  2582.          segment 40h, or the video memory.
  2583.  
  2584. ----- DMalloc ------------------------------------------- Page 37 of 52 -----
  2585.  
  2586.  
  2587. 6.7.1. DMalloc and atexit() processing
  2588.      DMalloc keeps monitoring the heap during atexit() or one-
  2589.      xit() processing. If there is any problem with the heap
  2590.      during that phase that causes DMalloc to pop up, you will
  2591.      see a blinking "atexit() processing" sign in the top right
  2592.      corner of the Information Window.
  2593.      This is also valid if you exit the program by selecting the
  2594.      "Exit Program" option from DMalloc (see section 5.3.1, page
  2595.      18).
  2596.  
  2597. 7. The Programming API
  2598.  
  2599.      The DMalloc API functions are defined and prototyped in the
  2600.      DMALLOC.H include file. If "_DMALLOC" is defined, the
  2601.      functions will be accessed. If "_DMALLOC" is undefined, all
  2602.      API functions are defined as "empty statements" so the
  2603.      source file will compile without errors.
  2604.  
  2605. 7.1. Activating the API
  2606.      At the top of each source file you want to compile with
  2607.      DMalloc information enabled, enter the following:
  2608.  
  2609.           #define _DMALLOC
  2610.           #include <dmalloc.h>
  2611.  
  2612.      Alternatively you could use the compiler switch
  2613.  
  2614.           -D_DMALLOC
  2615.  
  2616.      to enable the DMalloc API.
  2617.      Note: The file <dmalloc.h> must be included after any
  2618.            standard C include file (STDDEF.H, STDLIB.H).
  2619.  
  2620. 7.2. Removing the API Calls
  2621.      You can remove the DMalloc code from the program without
  2622.      recompiling by replacing the DMALLOC.LIB library with
  2623.      DMLNONE.LIB. This library provides dummy entries for all
  2624.      functions, and reroutes the DMalloc malloc function calls
  2625.      to the runtime library.
  2626.      Note: You must not link the DMALLOC.OBJ file to the program
  2627.            when linking with the DMLNONE.LIB library.
  2628.  
  2629.  
  2630.  
  2631.  
  2632.  
  2633.  
  2634.  
  2635.  
  2636.  
  2637.  
  2638.  
  2639.  
  2640.  
  2641.  
  2642.  
  2643.  
  2644.  
  2645.  
  2646.  
  2647. ----- DMalloc ------------------------------------------- Page 38 of 52 -----
  2648.  
  2649.  
  2650. 8. API Reference
  2651.      The following is the detailed reference for the DMalloc API
  2652.      calls. Please note that you must compile the source with
  2653.      DMalloc code enabled ("_DMALLOC" defined) in order to use
  2654.      the API.
  2655.  
  2656.  
  2657. void pascal DML_Trigger (void)
  2658.      Purpose:     Directs DMalloc to pop up.
  2659.      Parameters:  none
  2660.      Return:      void
  2661.      Remarks:     Actually this is a macro calling
  2662.                   DM_Trigger$(__FILE__, __LINE__).
  2663.  
  2664.  
  2665. unsigned pascal DML_Check (void)
  2666.      Purpose:     Directs DMalloc to check the heap. However, DMalloc
  2667.                   will not pop up if a problem has been found.
  2668.      Parameters:  none
  2669.      Return:      A nonzero value indicates that a new heap problem has
  2670.                   been detected. You may use the DML_Trigger() macro to
  2671.                   pop up in that case.
  2672.                   A zero value indicates no new problems found.
  2673.  
  2674.  
  2675. DML_CheckPop(void)
  2676.      Purpose:     Combines DML_Check() and DML_Trigger(). DMalloc will
  2677.                   check the heap and pop up if any problems are found,
  2678.                   regardless of the setting in the Setup Window (see
  2679.                   section 5.4.1, page 23).
  2680.      Parameters:  none
  2681.      Return:      void
  2682.      Remarks:     Implemented as a macro.
  2683.  
  2684.  
  2685.  
  2686.  
  2687.  
  2688.  
  2689.  
  2690.  
  2691.  
  2692.  
  2693.  
  2694.  
  2695.  
  2696.  
  2697.  
  2698.  
  2699.  
  2700.  
  2701.  
  2702.  
  2703.  
  2704.  
  2705.  
  2706.  
  2707.  
  2708.  
  2709.  
  2710. ----- DMalloc ------------------------------------------- Page 39 of 52 -----
  2711.  
  2712.  
  2713. void pascal DML_Setup (fAlert, fSaved, usPopCycles, usCheckCycles,
  2714.                        pszOwner, usLine)
  2715.      Purpose:     Modifies switches from the Setup Window
  2716.                   (see section 5.4, page 23).
  2717.      Parameters:  unsigned fAlert      SET_ON         "Yes"
  2718.                                        SET_OFF        "No"
  2719.                                        SET_UNCHANGED  keep current value
  2720.                   unsigned fSaved      SET_CORRUPTED  "Corrupted"
  2721.                                        SET_SAVED      "Saved"
  2722.                                        SET_BOTH       "Both"
  2723.                                        SET_OFF        "No"
  2724.                                        SET_UNCHANGED  keep current value
  2725.                   unsigned usPopCycles number         DMalloc pops up
  2726.                                                       regularly after this
  2727.                                                       number of calls
  2728.                                        SET_UNCHANGED  keep current value
  2729.                   unsigned usCheckCycles  number      DMalloc checks the
  2730.                                                       heap after this number
  2731.                                                       of calls
  2732.                                        SET_UNCHANGED  keep current value
  2733.                   char *pszOwner       char *         DMalloc pops up
  2734.                                                       whenever this file
  2735.                                                       calls the malloc
  2736.                                                       functions
  2737.                                        PSZ_UNCHANGED  keep current value.
  2738.                   unsigned usLine      number         narrows popup for a
  2739.                                                       source file to this
  2740.                                                       source line
  2741.                                        SET_UNCHANGED  keep current value
  2742.      Return:      void
  2743.  
  2744.  
  2745. void pascal DML_Select (fMalloc, fMarked, fNull, fData, fSystem,
  2746.                         pszOwner, usLine)
  2747.      Purpose:     modifies switches from the Selection Window
  2748.                   (see section 5.7, page 30). For each logical switch
  2749.                   you may specify either SET_ON, SET_OFF, or SET_UNCHANGED.
  2750.      Parameters:  unsigned fMalloc                    show allocated units
  2751.                   unsigned fMarked                    show only marked units
  2752.                   unsigned fNull                      show both NULL segment
  2753.                                                       entries
  2754.                   unsigned fData                      show the data segment
  2755.                                                       entries
  2756.                   unsigned fSystem                    show the system entries
  2757.                   unsigned pszOwner                   show only entries owned
  2758.                                                       by that source file
  2759.                                        PSZ_UNCHANGED  keep current value
  2760.                   unsigned usLine      number         narrows the source
  2761.                                                       file range to this
  2762.                                                       source line
  2763.                                        SET_UNCHANGED  keep current value
  2764.      Return:      void
  2765.  
  2766.  
  2767.  
  2768.  
  2769.  
  2770.  
  2771.  
  2772.  
  2773. ----- DMalloc ------------------------------------------- Page 40 of 52 -----
  2774.  
  2775.  
  2776. void pascal DML_SaveState (pSaveBuffer)
  2777.      Purpose:     Save the current DMalloc state to a save buffer.
  2778.      Parameters:  void *pSaveBuffer                   Pointer to the buffer
  2779.                                                       where the DMalloc
  2780.                                                       setup is to be stored
  2781.      Return:      void
  2782.      Remarks:     The setup contains all switch settings from the Setup
  2783.                   Window, the Selection Window, and the Colors Window.
  2784.                   You may use the handy DML_SAVEAREA macro to define a
  2785.                   local (or global) variable. If you are allocating a save
  2786.                   buffer be sure to provide at least DML_SAVESIZE bytes.
  2787.  
  2788.  
  2789. void pascal DML_RestoreState (pSaveBuffer)
  2790.      Purpose:     Restore a previously saved DMalloc state.
  2791.      Parameters:  void *pSaveBuffer                   Pointer to the buffer
  2792.                                                       where the DMalloc
  2793.                                                       setup is to be restored
  2794.                                                       from
  2795.      Return:      void
  2796.      Remarks:     The setup contains all switch settings from the Setup
  2797.                   Window, the Selection Window, and the Colors Window.
  2798.                   You may use the handy DML_SAVEAREA macro to define a
  2799.                   local (or global) variable. If you are allocating a save
  2800.                   buffer be sure to provide at least DML_SAVESIZE bytes.
  2801.                   There is no error correction. You must not use a buffer
  2802.                   that has not been previously filled by the DML_SaveState()
  2803.                   function.
  2804.  
  2805.  
  2806. unsigned pascal DML_Watchpoint (pUnit, fOnOff)
  2807.      Purpose:     Set or clear a Watchpoint
  2808.      Parameters:  void *pUnit          pointer        Pointer to an
  2809.                                                       allocated unit
  2810.                                        FAR_NULLCHECK  (un)tag the FAR_NULL
  2811.                                                       unit
  2812.                                        DATA_NULLCHECK (un)tag the _DATA unit
  2813.                   unsigned fOnOff      SET_ON         set a Watchpoint
  2814.                                        SET_OFF        remove a Watchpoint
  2815.                                        SET_UNCHANGED  keep Watchpoint status
  2816.      Return:      A nonzero value indicates that the Watchpoint has been set
  2817.                   or cleared. A zero value indicates that the pointer passed
  2818.                   to that function could not be found in DMalloc's tag table.
  2819.                   Specifying SET_UNCHANGED may be used to verify if the
  2820.                   pointer has been allocated by the malloc functions.
  2821.           Note:   without the _DMALLOC switch defined, this function will
  2822.                   always return nonzero.
  2823.  
  2824.  
  2825.  
  2826.  
  2827.  
  2828.  
  2829.  
  2830.  
  2831.  
  2832.  
  2833.  
  2834.  
  2835.  
  2836. ----- DMalloc ------------------------------------------- Page 41 of 52 -----
  2837.  
  2838.  
  2839. unsigned pascal DML_Savepoint (pUnit, fOnOff)
  2840.      Purpose:     Set or clear a Savepoint
  2841.      Parameters:  void *pUnit          pointer        Pointer to an
  2842.                                                       allocated unit
  2843.                   unsigned fOnOff      SET_ON         set a Savepoint
  2844.                                        SET_OFF        remove a Savepoint
  2845.                                        SET_UNCHANGED  keep Savepoint status
  2846.      Return:      A nonzero value indicates that the Savepoint has been set
  2847.                   or cleared. A zero value indicates that the pointer passed
  2848.                   to that function could not be found in DMalloc's tag table.
  2849.                   Specifying SET_UNCHANGED may be used to verify if the
  2850.                   pointer has been allocated by the malloc functions.
  2851.           Note:   without the _DMALLOC switch defined, this function will
  2852.                   always return nonzero.
  2853.  
  2854.  
  2855. void pascal DML_Breakpoint (fType)
  2856.      Purpose:     Trigger a debugger breakpoint
  2857.      Parameters:  unsigned fType       BPT_SOFTICE    set a Soft-ICE
  2858.                                                       breakpoint
  2859.                                        BPT_CODEVIEW   set a CodeView
  2860.                                                       breakpoint
  2861.                                        BPT_INT3       set a generic Int03
  2862.                                                       breakpoint
  2863.      Return:      void
  2864.      Remarks:     The debugger will get control at the statement following
  2865.                   the call to DML_Breakpoint().
  2866.  
  2867.  
  2868. void pascal DML_Disable (void)
  2869.      Purpose:     Completely disables DMalloc
  2870.      Parameters:  none
  2871.      Return:      void
  2872.      Remarks:     Normally this function need not be called. It completely
  2873.                   disables DMalloc, and after re-enabling it, any memory
  2874.                   unit allocated in the meantime will show up as MAVERICK
  2875.                   error, since DMalloc didn't know about it.
  2876.           Note:   Disabling increments a counter, thus, multiple calls to
  2877.                   DML_Enable (see below) are required to re-enable DMalloc.
  2878.  
  2879.  
  2880. void pascal DML_Enable (void)
  2881.      Purpose:     Enables DMalloc after disabling
  2882.      Parameters:  none
  2883.      Return:      void
  2884.      Remarks:     Enable DMalloc. Since DMalloc is enabled at the beginning,
  2885.                   this function is only necessary after calling DML_Disable.
  2886.  
  2887.  
  2888.  
  2889.  
  2890.  
  2891.  
  2892.  
  2893.  
  2894.  
  2895.  
  2896.  
  2897.  
  2898.  
  2899. ----- DMalloc ------------------------------------------- Page 42 of 52 -----
  2900.  
  2901.  
  2902. 9. Problem Solving, and Frequently Asked Questions
  2903.  
  2904.      Q:   When I'm pressing the [PrtSc] key, DMalloc doesn't pop
  2905.           up, but something else happens.
  2906.      A:   Three reasons are possible:
  2907.           ■    Your keyboard doesn't have a single [PrtSc] key.
  2908.                Try the [Shft]+[PrtSc] keys together.
  2909.           ■    Your program redirected interrupt 05h (the print-
  2910.                screen interrupt) for its own use. If this is the
  2911.                case, you cannot interactively popup DMalloc. DMal-
  2912.                locs heap cheker functionality will still be kept,
  2913.                and it will pop up whenever necessary.
  2914.                You may force DMalloc to pop up regularly by selec-
  2915.                ting a popup cycle count in the setup window (see
  2916.                section 5.4.3, page 24).
  2917.           ■    Some resident program is repeatedly changing inter-
  2918.                rupt 05h ([PrtSc] interrupt). Known programs are
  2919.                Pizzaz Plus, and HiJaak. Either unload these pro-
  2920.                grams, or modify their setup, if possible (e.g.
  2921.                HiJaak can be set to "semi-active").
  2922.  
  2923.      Q:   When I start the program, DMalloc doesn't come up with
  2924.           the Setup Window.
  2925.      A:   In the Setup Window, you have specified "No" at the
  2926.           "Startup Screen" entry. Either change this to "Yes", or
  2927.           simply delete the configuration file to restore the
  2928.           default setup.
  2929.  
  2930.      Q:   Whenever I run the program, DMalloc repeatedly pops up
  2931.           and shows an overwrite to the FARNULL region.
  2932.      A:   Some resident program is repeatedly changing interrupts
  2933.           that have been routed to your program. Interrupts used
  2934.           by the C runtime library and DMalloc are:
  2935.           ■    Int 00h - division by zero (runtime library)
  2936.           ■    Int 05h - print screen handler (DMalloc)
  2937.           ■    Int 16h - keyboard interrupt (DMalloc)
  2938.           ■    Int 21h - DOS OS entry (DMalloc)
  2939.           ■    Int 23h - Ctrl-C and Ctrl-Break handler (runtime
  2940.                library and DMalloc)
  2941.           Some resident programs hook one or more of these inter-
  2942.           rupts, and, using the timer tick, repeatedly reset
  2943.           them, bypassing the operating system. Known examples
  2944.           are Pizzaz Plus and HiJaak.
  2945.           Having loaded these programs, untag the topmost (FAR-
  2946.           NULL) entry in the Heap Window. This will disable
  2947.           checking of the FARNULL region.
  2948.  
  2949.      Q:   After an unrecoverable heap failure, the configuration
  2950.           file doesn't contain the corrupted pointers, only those
  2951.           I specified to "Save".
  2952.      A:   This is perfectly normal. Usually, when an unrecover-
  2953.           able heap error is encountered, you will notice a lot
  2954.           of different problems like overwritten pointers, and
  2955.           Maverick entries. To avoid confusion during the next
  2956.           session, DMalloc skips the corrupted pointers in that
  2957.           case, and only saves those specified for "Save".
  2958.  
  2959.  
  2960.  
  2961.  
  2962. ----- DMalloc ------------------------------------------- Page 43 of 52 -----
  2963.  
  2964.  
  2965.      Q:   The manual states that the configuration file name
  2966.           would be the same as the program name. Why is mine na-
  2967.           med "_DMALLOC.DMC" ?
  2968.      A:   DMalloc uses the environment information to retrieve
  2969.           the program name. If either your operating system do-
  2970.           esn't provide this information (DOS <3.0), or your pro-
  2971.           gram releases the environment for memory's sake, DMal-
  2972.           loc uses this name as a last resort.
  2973.  
  2974.      Q:   I had corrupted pointers, but DMalloc didn't remind me
  2975.           on the next session, even with the correct setup.
  2976.      A:   To have this feature work reliably, there are two
  2977.           things that must be kept in mind:
  2978.           ■    The environment settings, and the program parame-
  2979.                ters, should be the same. This is because the MSC
  2980.                startup code allocates some memory for these valu-
  2981.                es, and if the sizes of these units differ, so may
  2982.                the location of successively allocated units.
  2983.           ■    The size of the data segments should not change. If
  2984.                you have recompiled with somewhat modified code,
  2985.                this feature is most likely to fail.
  2986.           ■    It is absolutely necessary to do the same things
  2987.                you did in the last session, and in the same se-
  2988.                quence. If you're calling the malloc functions in
  2989.                different order, or with different parameters, the
  2990.                layout of the dynamic heap will be different, and
  2991.                the pointers will be different, too.
  2992.  
  2993.      Q:   I want to have NULLCHECK enabled, but DMalloc wouldn't
  2994.           let me tag the _DATA segment entry.
  2995.      A:   It is possible to disable the runtime library NULL
  2996.           check. If you provide a module containing a "_nullcheck()"
  2997.           (25) routine at link time, the linker will take this module
  2998.           instead of the one provided by the runtime library. Your
  2999.           _nullcheck() function must reside in the _TEXT segment and
  3000.           must return (int)0.
  3001.           In this case the linker will not link the NULL segment
  3002.           that normally makes up the first 4 paragraphs of the
  3003.           data segment. As the contents of these paragraphs are
  3004.           data of your program and no constant value anymore,
  3005.           Null Pointer assignments are perfectly valid. DMalloc
  3006.           is aware of this, and will not do Nullchecks on a
  3007.           non-constant data segment.
  3008.  
  3009.      Q:   I am using Bounds-Checker(tm), and so far my code seems
  3010.           to be clean. Now, having linked my program with DMal-
  3011.           loc, Bounds-Checker constantly pops up and complains.
  3012.      A:   You need to tell Bounds-Checker the exceptions needed
  3013.           for DMalloc. A file named DMALLOC.BC should be on the
  3014.           DMalloc original disk. Copy the contents of this file
  3015.           to your exception file, and Bounds-Checker should not
  3016.           complain any more.
  3017.  
  3018.  
  3019.  
  3020.      ____________________
  3021.  
  3022.      25  The actual name depends on the runtime library; this is what
  3023.          it's called in MSC.
  3024.  
  3025. ----- DMalloc ------------------------------------------- Page 44 of 52 -----
  3026.  
  3027.  
  3028.      Q:   Under DesqView, my program used to work. Now, having
  3029.           linked with DMalloc, I can see DMalloc's output, but my
  3030.           program's windows are gone!
  3031.      A:   DMalloc uses RLSI (Relocatable Screen Interface) for
  3032.           direct video access. Normally, if your program writes
  3033.           to the screen buffer directly, an RLSI host (as DV)
  3034.           would normally trap and relocate your memory access -
  3035.           your program is slower. Using RLSI, you'll get the ac-
  3036.           tual address of your video buffer. However, after RLSI
  3037.           has initialized, "standard" video accesses are not
  3038.           trapped anymore. Thus, your program writes to "nowhe-
  3039.           re".
  3040.           Refer to section 6.5.2 (page 31) on how to call the
  3041.           RLSI host.
  3042.  
  3043.      Q:   May I use DMalloc to debug a Windows program?
  3044.      A:   No, sorry. DMalloc cannot be used for a Windows pro-
  3045.           gram. You may use DMalloc for any DOS mode program,
  3046.           even if you're running it in a DOS window.
  3047.  
  3048.  
  3049.  
  3050.  
  3051.  
  3052.  
  3053.  
  3054.  
  3055.  
  3056.  
  3057.  
  3058.  
  3059.  
  3060.  
  3061.  
  3062.  
  3063.  
  3064.  
  3065.  
  3066.  
  3067.  
  3068.  
  3069.  
  3070.  
  3071.  
  3072.  
  3073.  
  3074.  
  3075.  
  3076.  
  3077.  
  3078.  
  3079.  
  3080.  
  3081.  
  3082.  
  3083.  
  3084.  
  3085.  
  3086.  
  3087.  
  3088. ----- DMalloc ------------------------------------------- Page 45 of 52 -----
  3089.  
  3090.  
  3091. Appendix A - The Library Serialization Program DMSerial
  3092.  
  3093. The unregistered shareware version of DMalloc contains a utili-
  3094. ty program that will serialize the shareware version of DMalloc
  3095. after you sent in your registration.
  3096.  
  3097. Together with the confirmation of your registration you will
  3098. receive a personal serialization code. Together with that code,
  3099. and your name, you may use the DMSerial program to remove the
  3100. shareware reminder screens from the DMalloc library.
  3101.  
  3102. To serialize the library, switch to the directory where you
  3103. installed DMalloc to, and type
  3104.  
  3105.      DMSERIAL [Enter]
  3106.  
  3107. at the DOS command prompt. DMSerial will respond with a short
  3108. explanation and ask
  3109.  
  3110.      Please enter the directory of DMALLOC.LIB, or press ^C to quit:
  3111.  
  3112. Now enter the directory of the DMalloc library. Note that you
  3113. must enter a directory. So if the library is in the current
  3114. directory, you must enter "." to specify the current directory.
  3115. Do not enter a filename!
  3116.  
  3117. If DMSerial finds the DMalloc shareware library, it prompts
  3118.  
  3119.      Please enter the user name (case sensitive!!), or press ^C to quit:
  3120.  
  3121. Enter the name you specified as the user name in the registra-
  3122. tion form. Take care that you write the name exactly as speci-
  3123. fied. The serialization program is case sensitive at this
  3124. point.
  3125.  
  3126. At the very last you are prompted to enter the serialization code:
  3127.  
  3128.    Please enter the serializer code (10 char), or press ^C to quit:
  3129.  
  3130.    (Enter the 10-digit serialization code you have been provided with.)
  3131.  
  3132. Your DMalloc (shareware) library is now serialized, and you
  3133. won't be bothered by the shareware reminder screens anymore.
  3134. You may now use the LIB program to remove the shareware notice
  3135. from the library, by typing
  3136.  
  3137.      LIB DMALLOC -DM_SWARE; [Enter]
  3138.  
  3139. at the DOS prompt. This will remove the object file containing
  3140. the notification texts from the library. If you don't want to
  3141. do that, you may use the /NOE switch on the linker's command
  3142. line to avoid linking the text to your programs.
  3143.  
  3144. Please do not distribute the serialized DMalloc library. Thank
  3145. you.
  3146.  
  3147.  
  3148.  
  3149.  
  3150.  
  3151. ----- DMalloc ------------------------------------------- Page 46 of 52 -----
  3152.  
  3153.  
  3154. Appendix B - The Library Configuration Program DMConfig
  3155.  
  3156. Registered users of DMalloc will receive a library configura-
  3157. tion program. As outlined in the manual (section 5.10, page
  3158. 28), DMalloc saves all configuration information, such as setup
  3159. information, colors, and display selection, to a configuration
  3160. file.
  3161.  
  3162. Using the DMConfig configuration program you may tailor the
  3163. library defaults directly to your specific needs, or create a
  3164. sample .DMC configuration file that you can use.
  3165.  
  3166. To execute DMConfig, type
  3167.      DMCONFIG [filename] [Enter]
  3168.  
  3169. at the DOS command prompt. The optional filename parameter can
  3170. be either the name of an existing .DMC configuration file, or
  3171. the name of the DMalloc library (including complete drive:\path
  3172. specification). DMConfig will detect the type of file you spe-
  3173. cified. If you specify a non-existing file, DMConfig assumes
  3174. that you want to create a .DMC configuration file with that
  3175. name.
  3176.  
  3177. DMConfig uses the same user interface as DMalloc. Available
  3178. windows are:
  3179.      ■    Setup
  3180.      ■    Colors
  3181.      ■    Select
  3182.      ■    Information
  3183.  
  3184. The Information Window allows you to choose between the follo-
  3185. wing actions:
  3186.      ■    Ignore and Exit
  3187.           Do nothing - simply exit the configuration program.
  3188.           This is the default if you didn't specify a filename on
  3189.           the command line.
  3190.      ■    Write to library DMALLOC.LIB
  3191.           Write the configuration information to the library.
  3192.           This is the default if you specified a library filename
  3193.           on the command line.
  3194.      ■    Create DMALLOC.DMC
  3195.           Create a (or write to an existing) configuration file.
  3196.           This is the default if you specified a configuration
  3197.           filename on the command line.
  3198.  
  3199.  
  3200.  
  3201.  
  3202.  
  3203.  
  3204.  
  3205.  
  3206.  
  3207.  
  3208.  
  3209.  
  3210.  
  3211.  
  3212.  
  3213.  
  3214. ----- DMalloc ------------------------------------------- Page 47 of 52 -----
  3215.  
  3216.  
  3217. Appendix C - The Legal Department (License Agreement)
  3218.  
  3219. Shareware distribution gives users a chance to try software before buying
  3220. it. If you try a shareware program and continue using it, you are expected
  3221. to register. Individual programs may differ on details - some request
  3222. registration while others require it, some specify a maximum trial period.
  3223. Registration often entitles the user for updates, printed documentation,
  3224. or other "perks".
  3225.  
  3226. Copyright laws apply to both shareware and commercial software, and the
  3227. copyright holder may retain all rights. The only meaningful difference
  3228. between shareware and commercial software is in the method of distribution.
  3229. Shareware authors specifically grant the rights to copy and distribute the
  3230. (unregistered) software/documentation, either to all and sundry or with
  3231. specific restrictions.
  3232.  
  3233. You should find software that suits your needs and bank account, whether it's
  3234. commercial or shareware. Both types have good programs and bad, but shareware
  3235. makes finding the right program easier, because you can try before you buy.
  3236. Also, because distribution overhead is much lower, shareware prices are often
  3237. lower, too. Finally, shareware has the ultimate money-back guarantee - if you
  3238. don't use it, you don't pay for it.
  3239.  
  3240. For this agreement, the term "DMalloc" refers to the DMalloc library and
  3241. include file (DMALLOC.LIB, DMLNONE.LIB and DMALLOC.H), the demonstration
  3242. program (DEMO.BAT, DEMO.TXT, and DMLDEMO.EXE) together with its accompanying
  3243. documentation (DMALLOC.DOC).
  3244.  
  3245.  
  3246.                              A G R E E M E N T
  3247.  
  3248.      DMalloc is "shareware" and is licensed at no charge to the user
  3249.      for evaluation. Feel free to share it, but you may not alter the
  3250.      program or documentation nor include DMalloc as part of another
  3251.      system. If you find this library useful and continue to use
  3252.      DMalloc after a 30 day trial period, you must make a registration
  3253.      payment to Ernest Vogelsinger. The registration fee will license
  3254.      one copy for use on one computer at any one time.
  3255.  
  3256.      For commercial users of DMalloc, and for those who want to include
  3257.      DMalloc within a beta-version of a program, very attractive
  3258.      site-license agreements may be obtained from Ernest Vogelsinger.
  3259.  
  3260.      Anyone distributing DMalloc for remuneration of any sort must first
  3261.      obtain authorization from Ernest Vogelsinger. Such authorization
  3262.      will automatically be granted to distributors recognized by the (ASP)
  3263.      as adhering to its guidelines for shareware distributors, and such
  3264.      distributors may begin offering DMalloc immediately. In either case,
  3265.      Ernest Vogelsinger must be advised.
  3266.  
  3267. You are encouraged to pass a copy of the unregistered DMalloc library, demo
  3268. program, and documentation along to your friends and colleagues for
  3269. evaluation. Please encourage them to register too. All registered users
  3270. receive the many benefits described in section 1.7, page 3.
  3271.  
  3272.  
  3273.  
  3274.  
  3275.  
  3276.  
  3277. ----- DMalloc ------------------------------------------- Page 48 of 52 -----
  3278.  
  3279. Appendix D - How to Send Email to Compuserve
  3280.  
  3281. The following information was put together by CompuServe's
  3282. Feedback team in a response time of less than 12 hours to my
  3283. inquiry. A very big thanks to all those people doing a wonder-
  3284. ful job!
  3285.  
  3286. D.1 How to obtain a CompuServe Account
  3287.      DMalloc is also supported via CompuServe, either on the
  3288.      CIS:MSLANG forum, Microsoft C (3) section, or via CompuSer-
  3289.      ve Mail (26). If do not have a CompuServe account, and
  3290.      want to obtain one, please contact
  3291.  
  3292.           CompuServe Customer Service
  3293.           800-848-8990
  3294.      or   (614) 457-8650
  3295.  
  3296.      To reach the MSLANG forum, type GO MSLANG at any CompuServe
  3297.      "!" prompt. To send a message follow the instructions of
  3298.      the forum software. Remember to post messages regarding
  3299.      DMalloc to section 3 (Microsoft C).
  3300.  
  3301.      To send email, type GO MAIL at any CompuServe "!" prompt.
  3302.      Follow the instructions from CompuServe. If you want to
  3303.      register DMalloc, send a note to 100015,551, stating your
  3304.      will to register, your Visa number, and that you agree to
  3305.      pay with your Visa account.
  3306.  
  3307.      If you have an account on a different network it is likely
  3308.      that you are able to send email to CompuServe. For some
  3309.      systems here's how to send email to CompuServe:
  3310.  
  3311. D.2 MCI
  3312.      ■    At MCI Mail's "Command:" prompt, type CREATE and press
  3313.           the [Enter] key.
  3314.  
  3315.      ■    At the "TO:" prompt, type my name, press [Space], type
  3316.           EMS within parenthesis and press the [Enter] key.
  3317.           For example:
  3318.                TO:           Ernest Vogelsinger (EMS) [Enter]
  3319.  
  3320.      ■    At the "EMS:" prompt, type COMPUSERVE and press the
  3321.           [Enter] key.
  3322.           For example:
  3323.                EMS:     COMPUSERVE [Enter]
  3324.  
  3325.           MCI Mail responds by displaying
  3326.                EMS281-6320 COMPUSERVE.
  3327.  
  3328.      ■    At the "MBX:" prompt, type my CompuServe User ID number
  3329.           and press [Enter] :
  3330.                MBX:     100015,551 [Enter]
  3331.  
  3332.      ■    At the second "MBX:" prompt, press [Enter].
  3333.  
  3334.  
  3335.  
  3336.           ____________________
  3337.  
  3338.           26  Formerly "Easyplex"
  3339.  
  3340. ----- DMalloc ------------------------------------------- Page 49 of 52 -----
  3341.  
  3342.  
  3343.      ■    The information that you have entered is displayed for
  3344.           your approval. You should type YES if correct or type
  3345.           NO if there is an error and press [Enter].
  3346.           For example:
  3347.                TO:           Ernest Vogelsinger
  3348.                EMS:     COMPUSERVE/ MCI ID: 281-6320
  3349.                MBX:     100015,551
  3350.  
  3351.                Is this address correct (Yes or No)?   YES [Enter]
  3352.  
  3353.      ■    At the next two prompts, "TO:" and "CC:", press [Enter]
  3354.           to skip them.
  3355.  
  3356.      ■    Now type your message and send it as any MCI Mail mes-
  3357.           sage. When unsure as to what to enter at any MCI Mail
  3358.           prompt, typing a [?] and pressing the [Enter] key will
  3359.           display an explanation of available options.
  3360.  
  3361.  
  3362. D.3 Internet
  3363.      Internet is an electronic mail system connecting governmen-
  3364.      tal institutions, military branches, educational institu-
  3365.      tions, and commercial companies. Only ASCII text messages
  3366.      up to 50,000 characters can be sent through this system.
  3367.  
  3368.      Internet is a connection of various systems. The message
  3369.      format will vary from one system to another. Check at your
  3370.      mail location for the correct format.
  3371.  
  3372.      Two things that must be known:
  3373.      ■    The User Id of Ernest Vogelsinger is 100015.551 (note
  3374.           that the comma changes to a period on Internet)
  3375.      ■    The CompuServe domain address is "compuserve.com".
  3376.  
  3377.      An typical example of the format used on the Internet sy-
  3378.      stem is:
  3379.  
  3380.           INTERNET: 100015.551@compuserve.com
  3381.  
  3382.      The format will vary, but the essential elements of the
  3383.      address will stay the same.
  3384.  
  3385.  
  3386. D.4 Telex, Twx
  3387.      CompuServe Mail allows to receive messages from any TELEX
  3388.      or TWX machine in the world.
  3389.  
  3390.      The information the TELEX user needs to send a message to a
  3391.      CompuServe electronic mailbox is:
  3392.  
  3393.      ■    The User Id (100015,551)
  3394.      ■    The machine number to send the message to:
  3395.                3762848 (which has the answerback of CompuServe)
  3396.  
  3397.      Specify on the first non-blank line of the message a "TO:"
  3398.      followed by the User ID to inform CompuServe Mail where to
  3399.      deliver the message.  If a subject is desired, you also can
  3400.      add an "RE:" after the "TO:" line in the message.
  3401.  
  3402.  
  3403. ----- DMalloc ------------------------------------------- Page 50 of 52 -----
  3404.  
  3405.  
  3406.      The format would look as follows:
  3407.           TO:       100015,551             (This is required)
  3408.                CompuServe Inc.             (This is optional)
  3409.           RE:       DMalloc Registration        (This is optional)
  3410.  
  3411.      Note:     If you are using another electronic mail service to
  3412.                generate a TELEX to be sent to CompuServe, you need
  3413.                to first verify you can place the "TO:" information
  3414.                on the first non-blank line of the message. Some
  3415.                electronic mail systems automatically insert other
  3416.                information at the top of an outbound TELEX making
  3417.                it impossible for CompuServe Mail to determine the
  3418.                correct address.
  3419.                EasyLink is an electronic mail service from which
  3420.                CompuServe cannot currently receive inbound TELE-
  3421.                Xes.
  3422.  
  3423.  
  3424.  
  3425. D.5 X.400
  3426.      The address that you should specify to a mail system which
  3427.      can route messages to CompuServe via an X.400 connection
  3428.      is:
  3429.  
  3430.           Country       = US
  3431.           ADMD      = CompuServe
  3432.           PRMD      = CSMail
  3433.           DDA           = 100015.551(note the period instead of a
  3434.                         comma)
  3435.  
  3436.      On AT&T Mail, for example, you could specify
  3437.           To:       mhs/c=us/ad=compuserve/pd=csmail/-
  3438.                     d.id=100015.551
  3439.  
  3440.      AT&T has defined a gateway named mhs!csmail that may repla-
  3441.      ce the c=, ad=, and pd= information. On AT&T, you could
  3442.      also specify
  3443.           To:       mhs!csmail!100015.551
  3444.  
  3445.      Note:     Again, the User Id must contain a period instead of
  3446.                a comma.
  3447.  
  3448.  
  3449.  
  3450.  
  3451.  
  3452.  
  3453.  
  3454.  
  3455.  
  3456.  
  3457.  
  3458.  
  3459.  
  3460.  
  3461.  
  3462.  
  3463.  
  3464.  
  3465.  
  3466. ----- DMalloc ------------------------------------------- Page 51 of 52 -----
  3467.  
  3468.  
  3469. D.6 MHS
  3470.      You can send MHS messages to the CompuServe Mail Hub. Spe-
  3471.      cify the message adressee as
  3472.           MAIL@CSERVE {100015,551}
  3473.  
  3474.      Note:     Some MHS applications do not have a specific proce-
  3475.                dure for entering the foreign address field. If you
  3476.                are unsure of the foreign address field capabili-
  3477.                ties of the MHS application, consult the documenta-
  3478.                tion or call the producers of the software to see
  3479.                if their package supports foreign address fields.
  3480.  
  3481.      If an MHS application does not specifically support the
  3482.      foreign address field, there may still be a way to address
  3483.      a message to a non-MHS address. In the space where the MHS
  3484.      address is normally entered, you may be able to enter the
  3485.      foreign address field. The foreign address field must be
  3486.      enclosed in braces.
  3487.  
  3488.      For example, at the TO: or CC: prompt enter:
  3489.           MAIL@CSERVE {100015,551}
  3490.  
  3491.  
  3492.  
  3493.  
  3494.  
  3495.  
  3496.  
  3497.  
  3498.  
  3499.  
  3500.  
  3501.  
  3502.  
  3503.  
  3504.  
  3505.  
  3506.  
  3507.  
  3508.  
  3509.  
  3510.  
  3511.  
  3512.  
  3513.  
  3514.  
  3515.  
  3516.  
  3517.  
  3518.  
  3519.  
  3520.  
  3521.  
  3522.  
  3523.  
  3524.  
  3525.  
  3526.  
  3527.  
  3528.  
  3529. ----- DMalloc ------------------------------------------- Page 52 of 52 -----
  3530.